# Examples of best practices in Jekyll?

**URL:** <https://talk.jekyllrb.com/t/examples-of-best-practices-in-jekyll/3798>\
**Category:** Help\
**Created:** [January 11, 2020, 6:17pm UTC](https://talk.jekyllrb.com/t/examples-of-best-practices-in-jekyll/3798 "2020-01-11T18:17:25Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![YJPL](https://yyz2.discourse-cdn.com/flex030/user_avatar/talk.jekyllrb.com/yjpl/32/1523_2.png) [@YJPL](https://talk.jekyllrb.com/u/YJPL)\
**Post date:** [January 11, 2020, 6:17pm UTC](https://talk.jekyllrb.com/t/examples-of-best-practices-in-jekyll/3798/1 "2020-01-11T18:17:25Z")

</div>

There are plenty of resources to build a site with Jekyll, starting with [https://jekyllrb.com](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?

---

<div class="post-metadata">

**Author:** ![ashmaroli](https://avatars.discourse-cdn.com/v4/letter/a/df705f/32.png) [@ashmaroli](https://talk.jekyllrb.com/u/ashmaroli)\
**Post date:** [January 12, 2020, 9:52am UTC](https://talk.jekyllrb.com/t/examples-of-best-practices-in-jekyll/3798/2 "2020-01-12T09:52:01Z")

</div>

You may start here: [https://github.com/benbalter/jekyll-style-guide](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.

---

<div class="post-metadata">

**Author:** ![ashmaroli](https://avatars.discourse-cdn.com/v4/letter/a/df705f/32.png) [@ashmaroli](https://talk.jekyllrb.com/u/ashmaroli)\
**Post date:** [January 12, 2020, 10:06am UTC](https://talk.jekyllrb.com/t/examples-of-best-practices-in-jekyll/3798/3 "2020-01-12T10:06:22Z")

</div>

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.