Examples of best practices in Jekyll?

Help
1

There are plenty of resources to build a site with Jekyll, starting with https://jekyllrb.com, various articles on the topic, and many repositories are available so we can look at the code. However, there are many ways to do the same things, so standards wouldn’t hurt when it comes to writing themes, etc.

What are some examples of best practices in Jekyll? Could you share these here?

2

You may start here: https://github.com/benbalter/jekyll-style-guide
Disclamier: It is not officially endorsed by Jekyll and may not reflect the styles followed by the active / popular members of the community.

Since a Jekyll theme repository can be forked and used like a conventional Jekyll source directory, the above style-guide can be applied to themes as well. However, when structuring, a theme-gem, the following is enforced by Jekyll itself:

  • Directories _layouts, _includes, _sass, and assets should be located at the root of the theme-gem for their contents to be read.
  • Their names are not configurable unlike their counterparts at the source directory.
  • Jekyll 4.0 allows bundling a config file as well. But it has to be named _config.yml and located at the root.

The following are not enforced but would be better if followed:

  • layout home.html for the index page.
  • layout page.html for standalone pages and documents.
  • layout post.html for posts in the site.

The above pattern is used by the theme Minima according to which the boilerplate site generated by jekyll new is set up. If third-party themes follow the same pattern, users need not edit their front matter each time they change themes.

2 Likes
3

When it comes to writing gem-based plugins (intended for consumption by the community),the following are recommended:

  • name the plugin with a leading jekyll- so that it is easily identified as a jekyll extension.
  • follow the Ruby style used in official plugins (from Jekyll org). You may use the gem rubocop-jekyll or manually copy the styles used at the jekyll repository. The benefit here is that the source code can be easily read by other developers in the Jekyll community due to similar structuring and formatting.
  • Avoid monkey-patching core Ruby classes and core Jekyll classes. Jekyll provides Hooks to easily modify behavior without monkey-patching. However, if monkey-patching cannot be avoided, document that explicitly to simplify debugging an unexpected bug.