A Quick Reference for Jekyll Syntax

Introduction If you just want to quickly set up a static site and don't have time to study syntax right now, I recommend directly forking my repository. For the official documentation, please refer to the official docs. This post covers only syntax, not other topics. For how to set up a blog, refer to this post. Configuration File Overview *config.yml Jekyll's global configuration lives in . This includes things like the site name, domain, and URL format. *includes For reusable parts of the site like the header, footer, and sidebar, it makes sense to extract them into separate files for easier maintenance, then include them where needed. Place these shared parts in this directory and include them with: {% raw %} {% endraw %} *layouts For site layout, we typically write templates so that when writing actual content — like a blog post — we can focus on the content itself and just specify which template to use with a tag. Content that specifies a template can be thought of as a "child" of that template. Why that analogy? Because templates can be nested multiple layers deep; the actual content is really just a template itself, just a leaf node. To include child content in a template: {% raw %} {% endraw %} To specify the parent template in the child: Note: this must appear at the very top of the child file. *posts Written content — such as blog posts — is typically stored here and usually acts as leaf nodes. data Also used for global variables, but for larger datasets. For example, if multiple people work on the site, you might define a file here. File contents might look like: Then in templates you can access this data with: site Where Jekyll outputs the generated site. This directory should generally be added to . index.html The homepage file. The extension is sometimes or others. You'll need to write this yourself, as there can be subtle differences between formats in certain situations. Static Assets For other static assets, you can place them directly in the root directory or any other directory. Paths work the same as on a regular website — just reference them by path. Configuring Global Variables Although global variables all have default values, we often set them manually to achieve our desired results. Source directory This generally doesn't need to be set; leave the default. It can also be specified at compile time, but when using , you cannot pass parameters. Output directory This is also typically left at the default: Safe switch The official documentation just says: Disable custom plugins, and ignore symbolic links. Exclude files This is very useful. Sometimes you have a file whose content you don't want to process — use this syntax to exclude those files. Force-include files Sometimes file names fall outside the range that would normally process. Force-include them here. For example, files. Timezone Templates often convert times, and without specifying a timezone the output time may be off by several hours. Encoding Template Syntax Template syntax is divided into two parts: frontmatter definitions and the syntax itself. Frontmatter The frontmatter is mainly used to specify the layout and define variables such as title, description, category/categories, tags, whether comments are enabled, and custom variables. Using Variables All variables are tree nodes. For example, variables defined in the frontmatter are accessed with: is the root node for the current page. The global root nodes are: - site — configuration from config.yml - page — the page's configuration info - content — used in templates to include child node content - paginator — pagination info Variables under - site.time — the time jekyll is run - site.pages — all pages - site.posts — all posts - site.relatedposts — 10 related posts; defaults to the 10 most recent; set lsi for similar posts - site.staticfiles — files not processed by jekyll, with attributes path, modifiedtime, and extname - site.htmlpages — all HTML pages - site.collections — new feature, haven't used it - site.data — data from the data directory - site.documents — all documents in all collections - site.categories — all categories - site.tags — all tags - site.[CONFIGURATIONDATA] — custom variables Variables under - page.content — page content - page.title — title - page.excerpt — excerpt - page.url — URL - page.date — date - page.id — unique identifier - page.categories — categories - page.tags — tags - page.path — source code location - page.next — next post - page.previous — previous post Variables under - paginator.perpage — number of posts per page - paginator.posts — posts on this page - paginator.totalposts — total number of posts - paginator.totalpages — total number of pages - paginator.page — current page number - paginator.previouspage — previous page number - paginator.previouspagepath — previous page path - paginator.nextpage — next page number - paginator.nextpagepath — next page path Character Escaping To output a literal , use to escape it. Outputting Variables Wrap a variable in double curly braces to output it. {% raw %} {% endraw %} Loops Very similar to interpreted languages. {% raw %} {% endraw %} Auto-generated Excerpts {% raw %} {% endraw %} Removing Specific Text deletes specified content from a variable. {% raw %} {% endraw %} Stripping Tags Useful when working with excerpts. {% raw %} {% endraw %} Code Highlighting {% raw %} {% endraw %} Array Size {% raw %} {% endraw %} Assignment {% raw %} {% endraw %} Formatting Dates {% raw %} {% endraw %} Searching by Key {% raw %} {% endraw %} Sorting {% raw %} {% endraw %} to json {% raw %} {% endraw %} Serialization Convert an object to a string. {% raw %} {% endraw %} Word Count {% raw %} {% endraw %} Limiting Results Get a subset of an array by specifying a range. {% raw %} {% endraw %} Content File Naming Convention For blog posts, the filename must follow the format . For example: {% raw %} {% endraw %} Cross-referencing Posts in Jekyll Cross-referencing posts is inevitable when blogging. For a Markdown file named , you can reference it with . Enabling the Drafts Feature For unfinished posts you don't want to publish, create a folder in the project directory and move those documents there. They won't appear in a normal build. However, if you start the server with , you'll be able to see all documents including drafts.