How Do We Apply the Hyde Theme to Existing Jekyll Site?

Abstract

This article will describe the process of applying Hyde theme on my existing Jekyll Bootstrap site. And this approach can be used for applying any theme of Jekyll. The main ideas of integrating the 3rd Jekyll Theme are:

• knowing the basic structure of Jekyll site,
• knowing the basic workflow of rendering HTML from Jekyll scripts,
• comparing the code differences between Hyde and your site,
• replacing code and test.

• Before Applying…
  • Start a Branch for Hyde
  • NO Need to be a Master of CSS or HTML
• Introduction of Jekyll
  • the Directory Structure of Jekyll
  • HTML Rendering Workflow
    • ./_layout/*.html, the Entrance of HTML
    • ./_includes/JB/*, the Utilities Scripts as the HTML Rendering Helper
    • ./_includes/themes/, the Layout Design of the Theme
    • ./assets/themes/, the CSS design, JavaScript or image of the Theme
• Steps of Installing Hyde into Existing Site
• Conclusions
• Encore

Before Applying…

Start a Branch for Hyde

Applying the Hyde to your existing Jekyll site is not a one-click step, so open a branch for Hyde applying, In case when you fail to apply Hyde and you want to revert changes and start over again.

NO Need to be a Master of CSS or HTML

I have very limited experience on CSS or HTML, so CSS for me is like RegEx, I can always check the CSS references, or seek help from stackoverflow when I face a styling problem.

Introduction of Jekyll

the Directory Structure of Jekyll

Check the official document on the folder structure of Jekyll:

Directory structure

For me, I used Jekyll-bootstrap 3 before. the directory structure has a little bit difference comparing with the original Jekyll.

.
├── assets
|   ├── css
|   ├── js
|   ├── img
|   └── themes
|       ├── # hyde
|       └── bootstrap
├── _includes
|   ├── JB
|   |   ├── comments_render_script
|   |   ├── pages_list_script
|   |   ├── analytics_render_script
|   └── themes
|       ├── # hyde
|       └── bootstrap
|           ├── default.html
|           ├── page.html
|           └── post.html
├── _layouts
|   ├── default.html
|   ├── page.html
|   └── post.html

Notice that there are two folders named themes, I will explain more letter. The Hyde theme will be installed into these two themes/ folder. You may read the source code and it’s easy to understand their usage.

HTML Rendering Workflow

This section will list the steps of rendering HTML by Jekyll. Again, reading the source code is useful, and it can help you apply other plugin / themes to your existing Jekyll site.

./_layout/*.html, the Entrance of HTML

the _layout folder is used for:

• configuration of the theme name,
• including the theme layout files, or installing the part of theme into your site.

Read the source code of any html file in _layout folder, and notice that:

• a variable named layout.theme.name has been defined in these html files, and it may be used for Jekyll 3. see issue #15,
• make sure the path correct in { % include % }.

./_includes/JB/*, the Utilities Scripts as the HTML Rendering Helper

JB stands for Jekyll Bootstrap, in this folder, you can find many useful scripts that are used for rendering a part of HTML:

• How do you want to display the comment section in your post,
• define some global variable, see ./_includes/JB/setup.

The scripts in JB/ are mainly used in ./_includes/themes/*, You will figure out the usage of utilities by searching { % include _includes/JB/setup % }

./_includes/themes/, the Layout Design of the Theme

The HTML layout design of theme, Jekyll Bootstrap or Hyde, can be found in this folder.

./assets/themes/, the CSS design, JavaScript or image of the Theme

Steps of Installing Hyde into Existing Site

Comparing the Hyde project to your existing site will tell you which files you need to install. The steps below based on my previous site.

1. open a branch for Hyde,
2. put hyde/public into your ./assets/themes/hyde/,
3. put hyde/_layout into your ./_includes/themes/hyde/,
4. also put hyde/_includes into your ./_includes/themes/hyde/,
5. see commit 235f6f6b3039 for files including,
6. compare the existing theme folder with hyde to determine the changes on hyde layout, for me, I compared ./_includes/theme/bootstrap with ./_includes/theme/hyde,
7. do a code review of ./_includes/theme/hyde based on your comparasion, make sure you merge the existing layout and correct path into Hyde theme, see my commit 1b2f41a3,
8. change the theme name in _config.yml, see my commit 4743d50a,
9. customize your site, see
   • git commit -m change on footer,
   • git commit -m enhanced related_posts,
   • git commit -m tags and about.
10. test and release.

Conclusions

For installing the theme of Jekyll:

• git flow feature start theme_name,
• copy CSS design into assets folder,
• copy layout design into _inlucdes/themes,
• change the configuration,
• compare code differences for issue solving,
• test and improving.

Encore

I am not with rich experiences on CSS and Jekyll, even on ruby. I mostly write Scala and <React.js />, so I will not spend much time on Jekyll theme unless someday, I have to.

So, in my opinion, Jekyll is used for writing the posts with coding, not used to keep decorating with Themes, unless designing becomes my major.

So, is there anyone can help me on a little design requirement below?

• For the post page including a Table of Content, short as [toc],
• reader scroll down the page, when he or she cannot see the [toc],
• I want to move the [toc] to the left sidebar automaticly,
• the mobile screen may need for another design,
• the main idea of this requirement is to select the section easily.

Thanks.