-
Notifications
You must be signed in to change notification settings - Fork 1
Website Jekyll Overview
Jekyll is a static site generator that constructs web pages from smaller written parts. This promotes flexibility and code reuse. For the SDG National Reporting Initiative website, to reduce dependency on Jekyll and keep the architecture more flexible, Jekyll is strictly being used as a page build system, with webpack handling most of the asset preparation.
The scope of this section is not to provide a complete understanding of how Jekyll works, but rather how it is used for this project. For Jekyll-specific questions, you can familiarize yourself with the official Jekyll documentation.
These are some of the fundamental components that you should be aware of:
- Front Matter
- Includes
- Templates
- Pages
Front matter is simply Jekyll-specific metadata. When front matter is included in a file, Jekyll will use those data when processing that file. Front matter is mostly used to help Jekyll understand how to build the website pages.
Located in the _includes directory, includes are "snippets" that can be injected into other pages or templates. This is useful if you have a section of content repeated across multiple pages.
For example, since most websites have the same head and footer structure for every page, it is common to implement the page head section as an include and the footer section as another include. Instead of having to manually edit the head and footers in every page, only the include files need to be edited. When Jekyll builds the website, the changes are reflected on every page that uses those includes.
Templates provide a standard structure into which both includes and page content can be injected. You can find templates in the _layouts directory.
Each Jekyll template should contain a special templating tag {{ content }}. Any page that utilizes the template will have its content substituted in place of the {{ content }} tag.
Page files are a little more flexible and nebulously defined in Jekyll. They can define full pages by themselves, or content to be inserted into a broader template. Pages operate with templates similarly to how includes work.
Page files use templates by defining a template in their front matter.
For the SDG National Reporting Initiative website, any pages not expected in the root directory (i.e. index.html and 404.html) should be located within the _pages directory.
When Jekyll runs a site build, typically kicked off by running the jekyll build or jekyll serve commands, it combines includes, pages, and templates into the finished pages which comprise the site. Whenever changes are made to the page components, Jekyll has to run a build to reflect those changes.
Jekyll automatically outputs its builds into the _site directory.