Here is an honest, practical comparison.

What is Jekyll?

Jekyll is a static site generator written in Ruby and officially supported by GitHub. You write content in Markdown, define layouts in Liquid templates, and Jekyll outputs a folder of plain HTML files. No JavaScript framework, no GraphQL, no build pipeline required.

It has been around since 2008 and powers hundreds of thousands of sites — including the official GitHub Pages platform.

Best for: blogs, documentation sites, portfolios, small business sites, and anyone who wants simplicity over features.

What is Gatsby?

Gatsby is a React-based static site framework that uses GraphQL as its data layer. It pulls content from anywhere — Markdown files, headless CMSs, REST APIs, databases — and compiles everything into optimised static files with automatic code splitting, image optimisation, and prefetching baked in.

Netlify acquired Gatsby in 2023. The framework is still actively maintained but is no longer the default choice for new React-based static projects, with Astro and Next.js (static export) taking significant market share.

Best for: content-heavy sites, e-commerce storefronts, sites pulling from multiple data sources, and teams already working in React.

Build speed

Jekyll is significantly faster to build, especially on small and medium sites. Gatsby’s build times grow steeply with content volume because of its GraphQL data layer and image processing pipeline.

Learning curve

Jekyll requires knowledge of Liquid templating and YAML front matter — both are simple and learnable in an afternoon. No JavaScript knowledge required beyond optional enhancements.

Gatsby requires React, GraphQL, and an understanding of Gatsby’s plugin ecosystem and data layer. If you already know React it is approachable. If you do not, it is a steep entry point just to publish a blog.

Winner for beginners: Jekyll by a wide margin.

Themes and design

Jekyll has a large ecosystem of free themes on GitHub, RubyGems, and marketplaces like JekyllHub. Themes are plain HTML/CSS/Liquid — easy to read, modify, and extend without tooling.

Gatsby themes are React components. They are more powerful (you can compose and shadow components) but require React knowledge to customise meaningfully. The Gatsby theme ecosystem is smaller and less active than it was in 2020–2022.

Winner for theme selection: Jekyll.

Plugins and ecosystem

Gatsby’s plugin ecosystem was once its biggest advantage — thousands of source and transformer plugins connect to every conceivable data source. That ecosystem is still there but growth has slowed since the Netlify acquisition.

Jekyll’s plugin ecosystem is smaller but covers all common needs: SEO, sitemaps, feeds, pagination, image optimisation, and syntax highlighting. The jekyll-* gem namespace has over 1,000 plugins.

Winner for integrations: Gatsby (still), though the gap has narrowed.

Hosting

Both deploy well to Netlify, Cloudflare Pages, and Vercel. Jekyll has one unique advantage: GitHub Pages hosts it natively, for free, with zero configuration. Push to a repository and your site is live.

Gatsby does not run on GitHub Pages natively (you need a GitHub Actions workflow to build and deploy).

Winner for free hosting: Jekyll.

Performance

Both generators produce static HTML, which means excellent performance out of the box. Gatsby adds automatic image optimisation via its gatsby-image / gatsby-plugin-image plugin, lazy loading, and link prefetching, which can push Lighthouse scores even higher.

For typical sites, both score 90+ on Core Web Vitals. Gatsby has a slight edge for image-heavy sites where its built-in processing pipeline matters.

Winner for out-of-the-box performance: Gatsby (marginally).

When to choose Jekyll

• You want a blog, portfolio, or documentation site with minimal setup
• You are not a JavaScript developer
• You want to host for free on GitHub Pages
• Your site has fewer than a few thousand pages
• You want themes you can understand and modify without a build step

When to choose Gatsby

• You are already building in React and want static output
• Your content comes from multiple sources (CMS + API + Markdown)
• You need advanced image optimisation built into the framework
• You are building a content-heavy e-commerce or news site
• Your team has React expertise and needs component composition

The bottom line

For most developers starting a blog, portfolio, or documentation site, Jekyll is the right choice. It is simpler, faster to set up, and cheaper to host. The themes are better, the GitHub Pages integration is seamless, and you will spend your time on content — not tooling.

If you are building something complex in React — pulling from a headless CMS, composing content from multiple APIs, or need advanced image processing — Gatsby earns its complexity. But in 2026, Astro is a strong contender for that use case too.

Browse free and premium Jekyll themes on JekyllHub to get started.

The React dependency: what it means in practice

Gatsby’s React dependency is its most consequential practical characteristic. Every Gatsby site is a React application — pages are React components, layouts are React components, even navigation and footers are React components. The benefit is access to React’s component model, hooks, and the broader npm ecosystem. The cost is a build pipeline that involves Babel, Webpack, React, GraphQL, and Gatsby’s own plugin and API layers.

For a developer fluent in React, this stack is comfortable. For a developer who wants to write Markdown and publish content, it is significant overhead. Installing Gatsby, understanding its GraphQL data layer, configuring plugins through gatsby-config.js, and debugging Webpack issues are all meaningfully more complex than the Jekyll equivalent (bundle install, write Markdown, bundle exec jekyll serve).

The complexity has a maintenance dimension too. Gatsby sites accumulate dependencies — gatsby plugins for every feature, npm packages for every utility — that require ongoing updates. A Gatsby site unattended for a year typically has dozens of outdated dependencies and potential breaking changes from Gatsby’s own version updates. A Jekyll site unattended for a year is typically still functional with a single bundle update.

GraphQL as a content layer: powerful but heavy

Gatsby’s GraphQL layer is genuinely innovative. Every data source — local files, CMS APIs, remote JSON, image metadata — is unified into a single queryable graph. A page component queries exactly the data it needs; Gatsby’s data layer fetches it during the build. The resulting pages are fast because they include only the data they need, not a full response from an API.

Jekyll’s data model is simpler and less abstract. Content comes from front matter, Markdown files, _data/ YAML files, and site.* variables — all accessed with straightforward Liquid syntax without querying. For sites with complex content relationships across many data sources, Gatsby’s unified data layer is genuinely more powerful. For sites with a standard blog structure — posts with metadata, categories, tags — Jekyll’s simpler model requires far less configuration to achieve the same result.

The GraphQL dependency also affects debugging. A Gatsby data error that traces back through a plugin’s GraphQL resolver can be difficult to diagnose without understanding Gatsby’s internal data layer architecture. A Jekyll template error that references a missing front matter field produces a clear, readable error message.

Image processing: Gatsby’s genuine strength

Gatsby’s image processing pipeline is a legitimate advantage for image-heavy sites. The gatsby-plugin-image component automatically generates multiple image sizes, converts to WebP, applies lazy loading, prevents layout shift with placeholder images, and selects the optimal size for the visitor’s viewport — all without manual configuration. The result is excellent Core Web Vitals scores on pages with many images, without the image optimisation work that Jekyll requires.

Jekyll’s image story requires more manual effort. jekyll-picture-tag provides a similar pipeline but requires configuration and is not enabled by default. Many Jekyll sites skip responsive images entirely, serving a single image size that is larger than necessary on mobile. The gap between Gatsby’s automatic image optimisation and Jekyll’s default “copy image unchanged” approach is real and significant for photographic sites.

For a photography portfolio, a recipe blog with multiple images per post, or a design showcase where image quality and loading performance are paramount, Gatsby’s image pipeline is worth the overhead. For a text-primarily blog or a technical documentation site where images are incidental, Jekyll’s image story is adequate.

Migration from Gatsby to Jekyll

The shift from Gatsby to Jekyll — often motivated by maintenance fatigue or a desire for simpler tooling — is a manageable but real migration. Your Markdown content files port directly; Jekyll and Gatsby both use Markdown with front matter, and the front matter conventions are similar enough that minimal renaming is needed. GraphQL queries in Gatsby page components have no Jekyll equivalent, so any page that fetches data from a CMS API requires reconfiguration against a Jekyll-compatible data source.

Component-based layouts in React become Liquid templates and includes. The logic is equivalent — conditional rendering, iteration, slot-based content injection — but the syntax is different. A developer comfortable with both React and Liquid can typically port a Gatsby theme to Jekyll in a week; a developer who has only used Gatsby takes longer.

The reverse migration (Jekyll to Gatsby) is similarly feasible for content; the main investment is building or adapting a Gatsby theme to match your existing design and configuring the GraphQL data layer for your content structure.

The verdict for 2026

Gatsby’s best years were 2018-2022, when it pioneered the concept of a React-based static site generator and built a large ecosystem around the idea. In 2023-2024, Astro emerged with a similar value proposition but lighter weight and the island architecture model. By 2026, developers choosing between a JavaScript-ecosystem static site generator and Jekyll are increasingly choosing Astro rather than Gatsby because Astro’s developer experience is better and its output is lighter.

For Jekyll vs Gatsby specifically: if you are building a content site, Jekyll is the simpler, lower-maintenance, lower-cost choice. If you are committed to React and need Gatsby-specific features (its image pipeline, its plugin ecosystem, GraphQL data layer), Gatsby remains the right tool for that use case — but those requirements are uncommon in purely content-driven sites.

The practical guidance: start with Jekyll unless you have a specific reason for Gatsby. You can always migrate to a React-based framework if the project’s requirements evolve to require it — and having a clean, well-structured Jekyll site as the starting point makes that migration easier than starting with a complex Gatsby configuration that you later want to simplify.

Processed files vs static files

Jekyll handles two categories of files:

Processed files — files with YAML front matter, or files in special directories (_posts/, _layouts/, _includes/, _sass/). Jekyll runs these through its build pipeline: Liquid templating, Markdown conversion, Sass compilation.

Static files — everything else. Jekyll copies them to _site/ unchanged. Images, fonts, JavaScript files, PDFs, videos — all copied as-is.

my-jekyll-site/
├── _posts/           ← processed (has front matter)
├── _sass/            ← processed (Sass compilation)
├── assets/
│   ├── images/       ← static (copied unchanged)
│   ├── fonts/        ← static (copied unchanged)
│   ├── js/           ← static (copied unchanged)
│   └── css/
│       └── main.scss ← processed (has front matter → compiled to CSS)

The assets/ folder convention

While Jekyll has no hard requirement for folder naming, assets/ is the universal convention for static files. Most themes use:

assets/
├── css/
│   └── main.scss        ← entry point for Sass (has front matter)
├── js/
│   ├── main.js
│   ├── bookmarks.js
│   └── search.js
├── images/
│   ├── logo.png
│   ├── social-card.png
│   ├── favicon.ico
│   └── blog/
│       ├── post-cover.webp
│       └── another-cover.webp
└── fonts/
    └── inter.woff2

Jekyll copies everything in assets/ to _site/assets/ during build. A file at assets/images/logo.png is served at https://example.com/assets/images/logo.png.

Referencing assets in templates

The relative_url filter

Always use relative_url when referencing assets in Liquid templates:

<link rel="stylesheet" href="{{ '/assets/css/main.css' | relative_url }}">
<script src="{{ '/assets/js/main.js' | relative_url }}" defer></script>
<img src="{{ '/assets/images/logo.png' | relative_url }}" alt="Logo">

relative_url prepends site.baseurl to the path. If your site has baseurl: "" (root domain), it changes nothing. If your site lives at a subdirectory (baseurl: "/my-project"), it correctly produces /my-project/assets/images/logo.png.

Without relative_url, assets break on sites with a non-empty baseurl.

The absolute_url filter

For Open Graph tags, sitemaps, or any place that needs a full URL:

<meta property="og:image" content="{{ '/assets/images/social-card.png' | absolute_url }}">

absolute_url prepends both site.url and site.baseurl.

In Markdown content

![Hero image](/assets/images/blog/hero.webp)

[Download PDF](/assets/files/guide.pdf)

Note: Markdown links do not go through relative_url. If you have a baseurl, use the HTML <img> tag inside your Markdown, or ensure your permalink structure accounts for the base URL.

In SCSS/CSS

Reference assets from CSS using relative paths from the CSS file’s location. Since assets/css/main.scss is in assets/css/, fonts and images are reached with ../:

@font-face {
  font-family: "Inter";
  src: url("../fonts/inter.woff2") format("woff2");
}

.hero {
  background-image: url("../images/hero-bg.webp");
}

Working with images

File formats in 2026

• WebP — best default choice. 25–35% smaller than JPEG at equivalent quality. Supported by all modern browsers.
• AVIF — even smaller than WebP but slower to encode. Good for images you generate offline.
• JPEG — use for photographs when WebP is not an option.
• PNG — use for images requiring transparency or exact colours (logos, icons).
• SVG — use for logos, icons, and illustrations. Infinitely scalable, tiny file size.

Converting images to WebP

# Single file
cwebp -q 85 image.jpg -o image.webp

# Batch convert all JPEGs
find assets/images -name "*.jpg" -exec sh -c   'cwebp -q 85 "$1" -o "${1%.jpg}.webp"' _ {} \;

# Using ImageMagick
mogrify -format webp -quality 85 assets/images/blog/*.jpg

Responsive images with srcset

For images that appear at different sizes across screen widths:

<img
  src="/assets/images/hero-800.webp"
  srcset="
    /assets/images/hero-400.webp 400w,
    /assets/images/hero-800.webp 800w,
    /assets/images/hero-1200.webp 1200w
  "
  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 800px"
  alt="Hero image"
  width="800"
  height="450"
  loading="lazy"
>

Generate multiple sizes during your build process (using Pillow, ImageMagick, or a Jekyll plugin like jekyll-responsive-image).

Always specify width and height

<img src="{{ post.image | relative_url }}" alt="{{ post.title }}" width="800" height="450">

Width and height attributes prevent Cumulative Layout Shift (CLS) — a Core Web Vitals metric — by letting the browser reserve the correct space before the image loads.

Lazy loading

<!-- Below-the-fold images — lazy load -->
<img src="..." alt="..." loading="lazy">

<!-- Above-the-fold images (hero, LCP element) — eager load -->
<img src="..." alt="..." loading="eager">

Use loading="lazy" on images that are not visible when the page loads. Never use it on your LCP (Largest Contentful Paint) element — the hero image or main post image.

The site.static_files variable

Jekyll provides a site.static_files variable that lists all static files (files copied without processing):

{% for file in site.static_files %}
  {{ file.path }}          → /assets/images/logo.png
  {{ file.basename }}      → logo
  {{ file.name }}          → logo.png
  {{ file.extname }}       → .png
  {{ file.modified_time }} → last modified date
{% endfor %}

Filter by extension or path:

{% assign images = site.static_files | where_exp: "f", "f.extname == '.webp'" %}
{% for image in images %}
  <img src="{{ image.path | relative_url }}" alt="{{ image.basename }}">
{% endfor %}

This is useful for auto-generating image galleries from files in a folder.

JavaScript files

Jekyll copies JavaScript files unchanged — no bundling, no transpilation. For simple sites, this is fine:

assets/js/
├── main.js         ← copied as-is
├── bookmarks.js    ← copied as-is
└── search.js       ← copied as-is

Reference in your layout:

<script src="{{ '/assets/js/main.js' | relative_url }}" defer></script>

Using Liquid in JavaScript files

If you need Jekyll variables in JavaScript (e.g. site data), add front matter to the JS file:

---
---
// assets/js/search-data.js

var SITE_DATA = {
  url: "{{ site.url }}",
  posts: [
    {% for post in site.posts %}
    {
      title: {{ post.title | jsonify }},
      url: "{{ post.url | relative_url }}",
      excerpt: {{ post.excerpt | strip_html | truncatewords: 30 | jsonify }}
    }{% unless forloop.last %},{% endunless %}
    {% endfor %}
  ]
};

Jekyll processes this file through Liquid (because of the front matter) and outputs JavaScript with the values baked in at build time.

Minifying JavaScript

Jekyll does not minify JS. Options:

1. Minify manually and commit the minified file
2. Use a build step (esbuild, rollup, or webpack) before Jekyll runs
3. Use a CDN for third-party libraries and serve your own JS unminified

For most Jekyll blogs, unminified JS is fine — the files are small and HTTP/2 handles multiple small requests efficiently.

Favicon files

Place favicon files in your project root or assets/ and reference in <head>:

assets/
├── favicon.ico          ← legacy IE fallback
├── favicon-16x16.png
├── favicon-32x32.png
├── apple-touch-icon.png  ← 180×180px for iOS
└── site.webmanifest     ← PWA manifest

<!-- _includes/head.html -->
<link rel="icon" type="image/x-icon" href="{{ '/favicon.ico' | relative_url }}">
<link rel="icon" type="image/png" sizes="32x32" href="{{ '/assets/favicon-32x32.png' | relative_url }}">
<link rel="icon" type="image/png" sizes="16x16" href="{{ '/assets/favicon-16x16.png' | relative_url }}">
<link rel="apple-touch-icon" sizes="180x180" href="{{ '/assets/apple-touch-icon.png' | relative_url }}">
<link rel="manifest" href="{{ '/assets/site.webmanifest' | relative_url }}">

Excluding assets from the build

Use exclude: in _config.yml to prevent source files (like uncompressed originals) from appearing in _site/:

exclude:
  - assets/images/originals/   # source files, not served
  - assets/fonts/source/       # font source files
  - tools/                     # build scripts
  - "*.psd"                    # Photoshop files
  - "*.ai"                     # Illustrator files

Cache busting

Because browsers cache static assets aggressively, changing a CSS or JS file may not update for returning visitors. Options:

Query string versioning — append a version number:

<link rel="stylesheet" href="{{ '/assets/css/main.css' | relative_url }}?v={{ site.version }}">

Update version: "1.2.3" in _config.yml after significant changes.

Filename hashing — include a hash in the filename (main.abc123.css). Requires a build pipeline; not supported natively by Jekyll.

Long cache headers with immutable assets — in _headers (Cloudflare/Netlify):

/assets/*
  Cache-Control: public, max-age=31536000, immutable

Use very long cache on assets with versioned filenames; use no-cache on HTML.

Summary: what goes where

Understanding this table — what Jekyll processes vs what it copies — explains nearly every “why is my file not showing up” or “why is my template not working” issue you will encounter.

Organising your assets folder for maintainability

A well-organised assets/ directory makes finding and updating files fast. The conventional structure is: assets/css/ for compiled stylesheets, assets/js/ for JavaScript files, assets/images/ for site-wide images, assets/fonts/ for self-hosted typefaces, and assets/icons/ for SVG icons or favicon variants. Post-specific images often go in a post-images subfolder organised by year or post slug to prevent the root images directory from becoming unmanageable.

Naming conventions matter more as the asset library grows. Use lowercase hyphenated names for all files (hero-background.webp rather than HeroBackground.WebP). Include dimensions in image filenames when you serve multiple sizes (logo-200w.webp, logo-400w.webp). Prefix JavaScript files that are page-specific rather than sitewide (post.js, home.js, theme-detail.js) to distinguish them from libraries. These conventions make the assets directory self-documenting and reduce the time spent hunting for a specific file.

Version your asset files explicitly when they change significantly. Jekyll does not have a built-in asset fingerprinting system (unlike Webpack or Vite), so browser caching can cause visitors to see stale CSS or JavaScript after an update. The simplest workaround is a version query string in _config.yml:

asset_version: "2025-12"

Reference it in your layout: main.css?v={{ site.asset_version }}. When you update CSS significantly, bump the version string and the new filename breaks the browser cache for all visitors. This is not as elegant as hash-based fingerprinting but is simple, reliable, and sufficient for most Jekyll sites.

Handling images efficiently in Jekyll

Images are the largest assets in most Jekyll sites and the primary target for performance optimisation. The goal is to serve each image at the smallest file size that maintains acceptable visual quality, in the correct format, at exactly the dimensions needed for the display context.

WebP is the correct format for photographs and complex images in 2025. It is smaller than JPEG at equivalent quality and supported by all modern browsers. PNG remains appropriate for logos, icons, and graphics with transparency or hard edges where lossless compression matters. Convert JPEG originals to WebP using ImageMagick or Squoosh before adding them to the assets folder — do not rely on on-the-fly conversion during builds, which is slow and increases build times.

For images that appear in multiple sizes — a cover image shown as a thumbnail on the blog index and full-width on the post page — provide multiple source files and use the srcset attribute in your HTML to let the browser select the appropriate size. The <picture> element with multiple <source> children gives you full control: WebP for modern browsers, JPEG fallback for older ones, and different crop ratios for different breakpoints if needed.

Store images in a dedicated folder rather than at the root of _posts/. Images co-located with post files work (Jekyll processes files in _posts/ subdirectories) but create clutter and make bulk operations on all images harder. A single assets/images/posts/ directory or an organisation by year (assets/images/2025/) keeps images findable and manageable.

JavaScript in Jekyll: the right amount

Jekyll’s JavaScript story is deliberate minimalism. The framework provides no JavaScript of its own — your theme and your customisations provide whatever JavaScript the site needs. This is a feature, not a limitation: it means you only load JavaScript you have consciously chosen to include.

Audit your theme’s JavaScript dependencies before using it. Open the network tab in browser DevTools and load the live demo. Check what scripts are loaded, how large they are, and whether they are render-blocking. A theme that loads jQuery (87KB gzipped) for dropdown menus that could be handled with 15 lines of vanilla JavaScript is carrying avoidable weight. A theme that loads a 50KB animation library for a hero section that animates only on first load is optimisable.

Modularise your JavaScript into page-specific files and load them conditionally. A post page should load post.js (table of contents, back-to-top button, copy-to-clipboard). The homepage loads home.js (carousel, testimonial rotation). The theme listing page loads themes.js (filtering, sorting, search). Loading all JavaScript on every page increases parse and execution time on pages that do not need it. Conditional loading — {% if page.layout == 'post' %}<script src="/assets/js/post.js" defer></script>{% endif %} in your layout — is a structural performance improvement that compounds across every page visit.

Static files as a deployment advantage

One of Jekyll’s most underappreciated properties is that every output file — HTML, CSS, JavaScript, images, fonts — is a static file that can be cached aggressively at the CDN edge. There are no API calls, no database queries, no server-side rendering that must complete before a response can be sent. Every resource the browser requests is pre-computed, pre-cached, and pre-positioned at an edge node near the visitor.

This architecture means a Jekyll site’s performance does not degrade under traffic spikes. The thousandth concurrent visitor gets the same response time as the first, because the response is a cached file delivered from a CDN node, not a dynamically generated page competing for server resources. For content that occasionally goes viral — a post that gets linked from a popular newsletter, a theme that gets featured on a high-traffic developer site — the static file architecture handles the traffic surge without additional cost or configuration.

Treat this architectural advantage as a reason to build your site correctly the first time: choose the right CDN host, configure caching headers properly, and optimise your build pipeline. The investment in static file architecture pays dividends every time a visitor loads a page, every time a search crawler indexes a URL, and every time traffic spikes beyond what a dynamic hosting tier would handle comfortably.

The _drafts folder

The simplest way to keep work-in-progress posts off your live site. Create a _drafts/ directory at your project root and put unfinished posts there:

_drafts/
├── jekyll-drafts-publishing-workflow.md
├── ideas-for-q3.md
└── half-finished-tutorial.md

Unlike _posts/, draft filenames do not need a date prefix:

# _posts/ — date required
_posts/2026-08-09-my-post.md

# _drafts/ — no date
_drafts/my-post.md

Previewing drafts locally

Normal jekyll serve ignores _drafts/ entirely. To preview your drafts:

bundle exec jekyll serve --drafts

When --drafts is active, Jekyll assigns today’s date to draft posts and includes them in the site. You can see exactly how a draft will look when published.

Drafts in CI/production

Your CI/CD build command should never include --drafts:

# Correct — drafts excluded
JEKYLL_ENV=production bundle exec jekyll build

# Wrong — would publish drafts
JEKYLL_ENV=production bundle exec jekyll build --drafts

Drafts are never published accidentally as long as you do not pass --drafts to your production build.

published: false

An alternative to _drafts/ — set published: false in any post’s front matter to exclude it from the build:

---
layout: post
title: "Work in Progress"
date: 2026-08-09
published: false
---

Content here will not appear on the live site.

This works for posts in _posts/ and pages anywhere on your site. Useful when:

• You want to keep the file in _posts/ (with a date) but not publish it yet
• You want to temporarily hide a published post without deleting it
• You want to keep old content for reference but remove it from the site

Preview unpublished content locally:

bundle exec jekyll serve --unpublished

Future-dated posts

Jekyll excludes posts whose date is in the future by default. Write a post today, set a future date, and it will automatically appear on your site on that date — the next time your site builds.

---
layout: post
title: "My Scheduled Post"
date: 2026-09-01
---

This post will not appear in site.posts until September 1, 2026 (or whenever you trigger a build after that date).

Preview future posts locally:

bundle exec jekyll serve --future

Scheduling posts with CI/CD

Future posts are only published when your site rebuilds after their date. If you do not rebuild frequently, a future post will sit in your repository unpublished.

Set up a scheduled CI/CD build to rebuild daily. On Netlify:

# Netlify → Site settings → Build hooks
# Add a build hook and schedule it with a cron service (cron-job.org)
# to trigger the hook daily at midnight

On GitHub Actions:

# .github/workflows/scheduled-build.yml
name: Scheduled Build

on:
  schedule:
    - cron: "0 0 * * *"   # midnight UTC every day

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: "3.2"
          bundler-cache: true
      - run: JEKYLL_ENV=production bundle exec jekyll build
      # add your deploy step here

Combining methods

The three approaches can be combined:

A practical editorial workflow for Jekyll

Here is a workflow that works well for solo writers and small teams:

Stage 1: Idea capture

Create a file in _drafts/ with just a title and outline:

<!-- _drafts/jekyll-pagination-guide.md -->
---
title: "Jekyll Pagination: The Complete Guide"
tags: [jekyll, pagination, tutorial]
---

## Outline

- What is pagination
- jekyll-paginate vs jekyll-paginate-v2
- Setup
- Customising the paginator
- SEO considerations

Stage 2: Writing

Fill in the content in _drafts/. Preview with jekyll serve --drafts at any point.

Stage 3: Review and polish

Run a local preview and check:

• All code examples work
• Images are in place
• Internal links resolve
• SEO: title, description, image set in front matter

Stage 4: Schedule or publish

Publish immediately: Move the file from _drafts/ to _posts/ and add today’s date:

mv _drafts/jekyll-pagination-guide.md    _posts/2026-08-09-jekyll-pagination-guide.md

Schedule for later: Move to _posts/ with a future date:

mv _drafts/jekyll-pagination-guide.md    _posts/2026-09-15-jekyll-pagination-guide.md

Keep hidden while finalising: Move to _posts/ with today’s date but published: false:

---
published: false
date: 2026-08-09
---

Set published: true (or remove the line) when ready.

Stage 5: Push and deploy

Commit and push. Your CI/CD pipeline builds and deploys the updated site.

Working with collaborators

For teams using GitHub:

Use pull requests for drafts. Writers work on a branch. Open a PR when the post is ready for review. Reviewers see a preview deployment (Netlify/Cloudflare/Vercel create these automatically). Merge when approved.

Use _drafts/ for long-running work. Content that spans multiple sessions lives safely in _drafts/ in its own branch.

Use published: false for quick feedback. Push to main with published: false to get a staging URL the reviewer can share without it going live.

Adding a headless CMS for non-technical editors

If your team includes non-developers who are not comfortable with Git and Markdown, add Decap CMS (formerly Netlify CMS) for a visual editing interface:

# admin/config.yml
collections:
  - name: drafts
    label: Drafts
    folder: _drafts
    create: true
    slug: "{{slug}}"
    fields:
      - { label: Title, name: title, widget: string }
      - { label: Body, name: body, widget: markdown }

  - name: posts
    label: Posts
    folder: _posts
    create: true
    slug: "{{year}}-{{month}}-{{day}}-{{slug}}"
    fields:
      - { label: Title, name: title, widget: string }
      - { label: Publish Date, name: date, widget: datetime }
      - { label: Published, name: published, widget: boolean, default: false }
      - { label: Body, name: body, widget: markdown }

Non-developers can write in a rich text editor and save as drafts. The published: false toggle keeps posts off the live site until ready.

Useful command reference

# Normal serve (no drafts, no future posts)
bundle exec jekyll serve

# Show all drafts
bundle exec jekyll serve --drafts

# Show future-dated posts
bundle exec jekyll serve --future

# Show unpublished posts (published: false)
bundle exec jekyll serve --unpublished

# Show everything
bundle exec jekyll serve --drafts --future --unpublished

# Production build (nothing extra)
JEKYLL_ENV=production bundle exec jekyll build

Tips for a smooth workflow

Name draft files descriptively. Even without dates, jekyll-pagination-complete-guide.md is much easier to find than draft-post-3.md.

Keep drafts short at first. Write the outline and key points, then expand. A complete outline in _drafts/ is better than a blank file in _posts/.

Commit drafts to Git. _drafts/ should be in your repository, not gitignored. This gives you version history, backup, and branch-based collaboration.

Set a date in front matter while drafting. Even if you are not ready to publish, set an estimated date in front matter so you can preview how it will sort among your posts.

Jekyll’s draft and publishing system is simple but complete. Once you have a consistent workflow, writing and scheduling content becomes as smooth as any CMS — with the added benefit of full version control.

Collaborative workflows with Jekyll drafts

For blogs with more than one author or editor, the drafts workflow needs structure beyond simply keeping files in _drafts/. Git branches provide the structure: each article in progress lives on its own branch, and the merge to main is the publishing action. This approach has several advantages over shared _drafts/ folders — authors work independently without seeing each other’s work-in-progress, editors can review by checking out the branch or viewing a pull request diff, and the history of each article is cleanly isolated.

Configure GitHub Actions to deploy preview branches automatically. With Netlify or Cloudflare Pages connected to your repository, every push to any branch creates a preview URL. An author writing on a branch named post/jekyll-seo-tips gets a preview at post-jekyll-seo-tips.yoursite.pages.dev. They can share this link for editorial review without requiring the reviewer to run Jekyll locally. The merge to main triggers a production deployment. This workflow is robust, version-controlled, and requires no CMS software.

For teams where authors are not comfortable with Git branching, Decap CMS layered on top of Jekyll provides a graphical interface for the same workflow. Decap CMS creates a GitHub PR for each draft when the editorial workflow is enabled — non-technical authors write in a rich text editor, and the underlying mechanism is the same branch-per-draft Git model. The technical implementation is identical; only the interface changes.

Scheduling posts in Jekyll

Jekyll does not have native post scheduling — it is a build tool, not a runtime server. Posts with future dates are excluded from the default build, which means scheduling requires triggering a build at the right time.

The cleanest scheduling approach is a GitHub Actions workflow with a cron trigger. Set up a workflow file that runs bundle exec jekyll build on a schedule — daily at midnight, for instance. Posts with dates up to and including that day are included in the build and thus appear on the site. Authors set the desired publication date in the post’s front matter and commit the file to the main branch; the scheduled build picks it up when the date arrives.

A sample GitHub Actions schedule trigger looks like:

on:
  schedule:
    - cron: '0 0 * * *'  # runs at midnight UTC daily
  push:
    branches: [main]

This runs the build on every push (for immediate publishing) and once daily at midnight (to publish scheduled posts). The combination ensures immediate deployment for posts dated today or earlier, and automatic publication for future-dated posts as their dates arrive.

Cloudflare Pages and Netlify both support build hooks — URLs you can POST to trigger a rebuild. Integrating a build hook with a CRON service (like EasyCron or GitHub Actions) gives you the same scheduled publishing capability on any host.

Handling editorial review before publishing

For high-stakes content — sponsored posts, legal content, press releases, guest contributions — a formal editorial review step before publishing adds quality assurance that informal drafts workflows lack. The Git pull request model provides this naturally: the author submits a PR from their draft branch, the editor reviews the diff, leaves comments, requests changes, and approves when satisfied. The merge to main publishes the post.

Within the PR, reviewers can leave line-level comments on specific sentences or paragraphs in the Markdown file. Authors address each comment, push revisions, and the reviewer re-reads. This iterative review process is identical to code review — and it works remarkably well for content because the diff format makes changes clear and the history is preserved permanently.

For teams uncomfortable with GitHub’s PR interface, Prose.io provides a graphical editor for Jekyll repositories that creates and edits files through the GitHub API. Authors write in a visual editor, save to a branch, and the tech-comfortable editor reviews and merges via the GitHub PR interface. The two groups never need to use the same tool; the Git repository is the shared layer.

From draft to evergreen: maintaining published content

Publishing is not the end of a post’s lifecycle. Evergreen technical content — how-to guides, comparison articles, reference posts — benefits from periodic updates to keep examples current, statistics accurate, and recommendations relevant. An update strategy prevents posts from becoming outdated and keeps rankings stable.

Add a last_updated field to post front matter when you make meaningful content changes. Configure your post layout to show both the original publication date and the last updated date when they differ — this signals to readers that the content is maintained, which increases trust and reduces bounce rates from readers who notice a date from three years ago and assume the content is stale.

Set a content review calendar: choose a frequency (quarterly for most posts, monthly for fast-moving topics) and review each published post against that schedule. The review questions are: Is the information still accurate? Have any links broken? Are there new alternatives or tools worth mentioning? Has the recommended approach changed? A thirty-minute review session per post, twice a year, keeps a blog of fifty posts in excellent condition without feeling overwhelming.

Jekyll’s Git history makes content archaeology easy — you can see exactly what changed in a post at any point in its history, which is useful for understanding why something was written a certain way or when a specific claim was added. This transparency is one of the underrated long-term benefits of a Git-based content workflow over a database-driven CMS where content history is often opaque or unavailable.

Sass vs SCSS

Sass has two syntaxes:

SCSS (Sassy CSS) — superset of CSS. Valid CSS is valid SCSS. Uses curly braces and semicolons. The most common syntax.

Sass (indented syntax) — uses indentation instead of braces, no semicolons. Older syntax, less commonly used.

Jekyll supports both. This guide uses SCSS (the .scss extension).

Jekyll’s Sass directory structure

Jekyll processes Sass files with this convention:

• Files in _sass/ starting with _ are partials — they are imported by other files, never compiled directly
• Files in assets/css/ (or anywhere outside _sass/) with .scss extension and front matter are entry points — Jekyll compiles these to CSS

_sass/                     ← partials live here
├── _variables.scss
├── _base.scss
├── _nav.scss
├── _cards.scss
└── _post.scss

assets/
└── css/
    └── main.scss          ← entry point — compiled to main.css

Creating the entry point

The entry point file needs front matter (even if empty) to tell Jekyll to process it:

/* assets/css/main.scss */
---
---

@import "variables";
@import "base";
@import "nav";
@import "cards";
@import "post";

The empty --- block is required. Without it, Jekyll copies the file as-is without processing.

Import partials without the leading _ or .scss extension — Sass resolves them automatically.

SCSS partials in _sass/

_variables.scss — design tokens

// _sass/_variables.scss

// Colours
$color-primary:    #2563eb;
$color-primary-dark: #1d4ed8;
$color-text:       #1a1a2e;
$color-muted:      #6b7280;
$color-border:     #e5e7eb;
$color-bg:         #ffffff;
$color-bg-alt:     #f9fafb;

// Typography
$font-sans:        "Inter", system-ui, -apple-system, sans-serif;
$font-mono:        "Fira Code", "Cascadia Code", monospace;
$font-size-base:   1rem;
$line-height-base: 1.6;

// Spacing
$spacing-xs:   0.25rem;
$spacing-sm:   0.5rem;
$spacing-md:   1rem;
$spacing-lg:   1.5rem;
$spacing-xl:   2rem;
$spacing-2xl:  3rem;

// Layout
$container-max: 1200px;
$sidebar-width: 280px;

// Borders
$radius-sm:  4px;
$radius-md:  10px;
$radius-lg:  16px;
$radius-full: 9999px;

// Shadows
$shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
$shadow-md: 0 4px 6px rgba(0, 0, 0, 0.07);
$shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);

// Transitions
$transition-fast:   150ms ease;
$transition-base:   250ms ease;
$transition-slow:   400ms ease;

_base.scss — reset and global styles

// _sass/_base.scss
@import "variables";

*,
*::before,
*::after {
  box-sizing: border-box;
}

html {
  font-size: 16px;
  -webkit-text-size-adjust: 100%;
}

body {
  margin: 0;
  font-family: $font-sans;
  font-size: $font-size-base;
  line-height: $line-height-base;
  color: $color-text;
  background: $color-bg;
}

img {
  max-width: 100%;
  height: auto;
  display: block;
}

a {
  color: $color-primary;
  text-decoration: none;

  &:hover {
    text-decoration: underline;
  }
}

h1, h2, h3, h4, h5, h6 {
  line-height: 1.3;
  font-weight: 700;
  margin-top: 0;
}

code {
  font-family: $font-mono;
  font-size: 0.875em;
  background: $color-bg-alt;
  padding: 0.15em 0.4em;
  border-radius: $radius-sm;
}

SCSS features used in Jekyll themes

Variables

$color-primary: #2563eb;

.btn {
  background: $color-primary;
  
  &:hover {
    background: darken($color-primary, 10%);
  }
}

Nesting

.card {
  border-radius: $radius-md;
  overflow: hidden;
  
  &__image {
    width: 100%;
    aspect-ratio: 16 / 9;
  }
  
  &__body {
    padding: $spacing-lg;
  }
  
  &__title {
    font-size: 1.125rem;
    font-weight: 600;
    margin: 0 0 $spacing-sm;
  }
  
  &--featured {
    border: 2px solid $color-primary;
  }
  
  &:hover {
    box-shadow: $shadow-md;
  }
}

This BEM-style nesting (&__element, &--modifier) generates classes like .card__image, .card__body, .card--featured.

Mixins

// _sass/_mixins.scss

@mixin flex-center {
  display: flex;
  align-items: center;
  justify-content: center;
}

@mixin truncate {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

@mixin responsive($breakpoint) {
  @if $breakpoint == mobile {
    @media (max-width: 640px) { @content; }
  } @else if $breakpoint == tablet {
    @media (max-width: 1024px) { @content; }
  } @else if $breakpoint == desktop {
    @media (min-width: 1025px) { @content; }
  }
}

// Usage
.nav {
  @include flex-center;
  
  @include responsive(mobile) {
    flex-direction: column;
  }
}

.card__title {
  @include truncate;
}

Functions

// Convert px to rem
@function rem($px) {
  @return ($px / 16) * 1rem;
}

.heading {
  font-size: rem(24);  // → 1.5rem
}

// Darken a colour by percentage
.btn:hover {
  background: darken($color-primary, 8%);
}

// Generate a colour with opacity
.overlay {
  background: rgba($color-text, 0.5);
}

Extends / placeholders

%visually-hidden {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

.sr-only {
  @extend %visually-hidden;
}

.skip-link:focus {
  @extend %visually-hidden;
  clip: auto;
  width: auto;
  height: auto;
}

Dark mode with Sass

// _sass/_variables.scss

// Light mode defaults (also used as CSS custom properties)
:root {
  --color-bg:     #{$color-bg};
  --color-text:   #{$color-text};
  --color-border: #{$color-border};
  --color-bg-alt: #{$color-bg-alt};
}

// Dark mode overrides
:root[data-theme="dark"],
.dark {
  --color-bg:     #0f172a;
  --color-text:   #f1f5f9;
  --color-border: #1e293b;
  --color-bg-alt: #1e293b;
}

// Use CSS custom properties throughout
body {
  background: var(--color-bg);
  color: var(--color-text);
}

.card {
  border-color: var(--color-border);
  background: var(--color-bg-alt);
}

This approach — setting CSS custom properties from Sass variables — gives you the best of both worlds: Sass for authoring, CSS variables for runtime dark mode toggling with JavaScript.

Sass compilation settings in _config.yml

# _config.yml
sass:
  sass_dir: _sass          # where partials live (default: _sass)
  style: compressed        # compressed | expanded | nested | compact
  load_paths:
    - _sass
    - node_modules         # if importing npm packages

style options:

• compressed — removes all whitespace, one-line output. Use for production.
• expanded — each rule and property on its own line. Default in development.
• nested — rules nested to reflect the SCSS structure.
• compact — one rule per line.

Most setups use compressed in production builds:

sass:
  style: compressed

Importing npm Sass packages

If you install Sass libraries via npm, add the path to load_paths:

npm install sass-mq normalize.css

sass:
  load_paths:
    - _sass
    - node_modules

// assets/css/main.scss
---
---
@import "normalize.css/normalize";
@import "sass-mq/mq";
@import "variables";
@import "base";

Organising a production-ready _sass/ directory

_sass/
├── _variables.scss      ← design tokens
├── _mixins.scss         ← reusable mixins
├── _functions.scss      ← Sass functions
├── _reset.scss          ← CSS reset/normalise
├── _base.scss           ← global styles (body, a, h1-h6, img)
├── _typography.scss     ← prose/content typography
│
├── layout/
│   ├── _container.scss
│   ├── _grid.scss
│   └── _sections.scss
│
├── components/
│   ├── _nav.scss
│   ├── _footer.scss
│   ├── _cards.scss
│   ├── _badges.scss
│   ├── _buttons.scss
│   ├── _forms.scss
│   └── _modals.scss
│
├── pages/
│   ├── _home.scss
│   ├── _blog.scss
│   ├── _theme-detail.scss
│   └── _authors.scss
│
└── utilities/
    ├── _helpers.scss    ← .sr-only, .clearfix, etc.
    └── _dark-mode.scss

/* assets/css/main.scss */
---
---

// Tokens and tools
@import "variables";
@import "mixins";
@import "functions";

// Base
@import "reset";
@import "base";
@import "typography";

// Layout
@import "layout/container";
@import "layout/grid";
@import "layout/sections";

// Components
@import "components/nav";
@import "components/footer";
@import "components/cards";
@import "components/badges";
@import "components/buttons";
@import "components/forms";

// Pages
@import "pages/home";
@import "pages/blog";
@import "pages/theme-detail";
@import "pages/authors";

// Utilities
@import "utilities/helpers";
@import "utilities/dark-mode";

Common mistakes

Missing front matter on the entry point: Without the --- block, Jekyll copies main.scss as a plain text file instead of compiling it. Always include the empty front matter.

Importing from the wrong path: Partials in _sass/ are imported without the leading _ or the directory path. If your partial is _sass/components/_nav.scss, import it as @import "components/nav".

Using @use instead of @import: Jekyll’s built-in Sass processor uses libsass which supports @import but has limited support for the newer @use syntax. Stick with @import for Jekyll’s native Sass processing. If you need @use, switch to a Node.js PostCSS pipeline.

Not compressing in production: Add sass: style: compressed to _config.yml or use a production build command to minimise CSS output.

Built-in Sass support is one of Jekyll’s most useful features. No Node.js, no build pipeline, no configuration — just write SCSS and Jekyll compiles it. For most Jekyll sites, the built-in processor is all you need.

Why Jekyll’s built-in Sass is enough for most sites

The built-in Sass processor handles the vast majority of use cases without any additional tooling. You get variables, nesting, mixins, functions, partials, and the ability to import npm packages via load_paths. For blogs, documentation sites, portfolios, and small business sites, this is everything you need.

The case for adding a Node.js build pipeline (PostCSS, Webpack, Vite) only becomes compelling when you need features the built-in processor cannot provide: Tailwind CSS utilities, PostCSS plugins like autoprefixer for vendor prefixes at scale, or the newer Sass @use/@forward module system. For most Jekyll sites, the complexity of adding a Node.js pipeline outweighs the benefits.

Start with Jekyll’s built-in Sass. Add a Node.js pipeline only when you have a specific, concrete reason that the built-in processor cannot address.

Writing maintainable SCSS for Jekyll themes

SCSS is a powerful tool, but it is also one that is easy to misuse. A few discipline practices keep Jekyll theme stylesheets maintainable over time.

Use CSS custom properties for runtime values, Sass variables for build-time values. Sass variables compile away — you cannot change them with JavaScript. CSS custom properties (--color-primary: blue) are accessible at runtime, making them essential for dark mode toggles, user preference systems, and theme switchers. The best practice is to define your design tokens as Sass variables and then assign them to CSS custom properties in :root:

$blue-600: #2563eb;
$blue-700: #1d4ed8;

:root {
  --color-primary:      #{$blue-600};
  --color-primary-dark: #{$blue-700};
}

// Use the custom property everywhere (not the Sass variable)
.btn {
  background: var(--color-primary);
  &:hover { background: var(--color-primary-dark); }
}

This gives you the authoring convenience of Sass variables for defining the palette, and the runtime flexibility of CSS custom properties for applying them.

Avoid deep nesting. Nesting beyond three levels creates high-specificity selectors that are hard to override and indicate overly coupled HTML and CSS. A good rule: if you cannot read the compiled selector at a glance, the nesting is too deep. BEM naming with one level of nesting (&__element, &--modifier) produces clear, flat selectors without sacrificing the readability benefits of nesting.

Keep files focused. A _nav.scss file should contain only nav-related styles. When a file grows beyond 150–200 lines, consider splitting it. A _nav-desktop.scss and _nav-mobile.scss approach is sometimes cleaner than one large file with breakpoints scattered throughout.

Comment at the section level, not the line level. A comment explaining what a block of CSS achieves is valuable. A comment explaining what a single property does is usually not. Exception: non-obvious values like magic numbers, z-index values, and vendor-specific hacks benefit from inline comments explaining why they are there.

The @use and @forward system (Dart Sass)

Jekyll’s built-in Sass processor uses LibSass, which supports the older @import syntax. Dart Sass (the reference implementation) introduces @use and @forward as replacements that offer better encapsulation:

// @use namespaces modules automatically
@use "variables" as vars;
@use "mixins";

.btn {
  background: vars.$color-primary;
  @include mixins.flex-center;
}

@use prevents global namespace pollution by scoping module members under a namespace. @forward re-exports module members, useful for building a single entry point that exposes multiple partials.

If you want to use @use with Jekyll, you need to replace the built-in Sass processor with a Node.js-based pipeline using sass (the Dart Sass npm package) and PostCSS. The setup is more complex but enables the full modern Sass feature set.

For most Jekyll projects, the added complexity is not worth it. The @import system, while deprecated in Dart Sass, works perfectly well with Jekyll’s LibSass processor and will continue to do so for the foreseeable future.

Performance: how much CSS is too much?

The impact of your CSS file size on performance depends on how it is delivered. Jekyll’s built-in Sass with style: compressed produces minified CSS — no whitespace, comments stripped. This is important for production builds.

A rough guide: CSS under 50kb (uncompressed) has negligible performance impact on modern connections. Between 50kb and 150kb, the file size is noticeable on slower connections but unlikely to cause Lighthouse score problems. Above 150kb, you are probably including unused styles and should consider audit tooling.

For Jekyll themes, CSS bloat typically comes from including large third-party stylesheets (Bootstrap, Foundation, Bulma) without purging unused rules. If you import Bootstrap via npm and use only a fraction of its utilities, you are shipping tens of kilobytes of unused CSS.

The solution for third-party framework CSS is either to import only the specific component files you need:

// Import only Bootstrap's grid and buttons, not everything
@import "bootstrap/scss/grid";
@import "bootstrap/scss/buttons";
@import "bootstrap/scss/utilities/api";

Or to use a tool like PurgeCSS to remove unused rules from the production build. For Jekyll with a PostCSS pipeline, @fullhuman/postcss-purgecss scans your HTML and template files and removes any CSS rules that do not match used class names.

For most Jekyll sites that write their own SCSS rather than importing a large framework, CSS file size is not a meaningful concern. Write clear, modular stylesheets using the conventions in this guide, compress them in production, and focus on the variables and patterns that make your site easy to maintain and customise over time.

Explore the JekyllHub theme collection to see SCSS-driven Jekyll themes in action — the best themes demonstrate these conventions cleanly and serve as excellent references for your own SCSS architecture.

Debugging Sass compilation errors

When Jekyll’s Sass processor encounters an error, it stops the build and reports the file and line number. The error messages from LibSass are generally clear, but a few common patterns trip up beginners.

“Undefined variable” — you referenced a variable ($color-primary) before declaring it or in a file that does not import _variables.scss. Fix: add @import "variables" at the top of the partial that uses the variable.

“File to import not found” — the partial path in the @import statement does not match the actual filename. Check for typos and remember that partial filenames start with _ but are imported without it: @import "nav" imports _sass/_nav.scss.

“Invalid CSS after” — a syntax error in your SCSS. LibSass’s error messages point to a line but the actual error is sometimes a few lines earlier — an unclosed bracket or missing semicolon from a previous rule.

No error but CSS unchanged — Jekyll cached the previous build. Run bundle exec jekyll clean then bundle exec jekyll serve to force a fresh compilation.

For faster debugging cycles, use bundle exec jekyll serve with the --incremental flag during active CSS development — Jekyll only rebuilds changed files, dramatically reducing the time between saving a SCSS change and seeing it in the browser. When using --incremental, you may need to run a full clean build periodically to ensure all files are in sync.

Moving forward with Jekyll SCSS

Once you have the fundamentals working — imports, variables, mixins, and a sensible file structure — you have everything you need to write maintainable, scalable styles for any Jekyll project. The key habits to develop are keeping your SCSS partials small and focused, using variables for anything that appears more than once, and compiling locally so you catch errors before pushing to production.

How Jekyll builds URLs by default

By default, Jekyll mirrors your file structure. A file at _posts/2026-08-07-my-post.md generates a URL like /2026/08/07/my-post/. A page at about.md generates /about/.

But the default is rarely what you want for production. The permalink setting in _config.yml (and in individual file front matter) lets you control this precisely.

The permalink setting

Set a global permalink pattern in _config.yml:

permalink: /blog/:title/

This tells Jekyll: every post’s URL should be /blog/ followed by the post’s title-slug.

Built-in permalink styles

Jekyll ships with several named permalink patterns:

permalink: date      # /year/month/day/title.html
permalink: pretty    # /year/month/day/title/  (trailing slash, no .html)
permalink: ordinal   # /year/ordinal/title.html
permalink: weekdate  # /year/week/short_day/title/
permalink: none      # /title.html

Most sites use pretty or a custom pattern. date (the historical default) produces cluttered URLs. none creates flat URLs with .html extensions.

Permalink placeholders

Build custom patterns using these placeholders:

Common custom patterns

# Clean blog URL — most common for blog sites
permalink: /blog/:title/

# With date — good for news sites
permalink: /:year/:month/:title/

# Category-based
permalink: /:categories/:title/

# Flat — no nesting
permalink: /:title/

# With date and category
permalink: /:categories/:year/:month/:day/:title/

Recommended permalink for most Jekyll blogs

permalink: /blog/:title/

This gives you:

• Clean, readable URLs: /blog/jekyll-front-matter-guide/
• No date in the URL (posts stay relevant even when old)
• Consistent /blog/ prefix separating blog content from pages
• Easy to remember and share

Avoid including dates in permalinks unless you publish time-sensitive content (news, changelogs) where date context adds value.

Per-page permalink override

Override the global setting in any file’s front matter:

---
layout: page
title: "About"
permalink: /about/
---

---
layout: post
title: "My Special Post"
permalink: /featured/my-special-post/
---

The front matter permalink always wins over the global setting in _config.yml.

Permalinks for pages

Pages (in _pages/ or the root directory) use the same permalink front matter key:

---
layout: page
title: "Browse Themes"
permalink: /themes/
---

---
layout: page
title: "Submit a Theme"
permalink: /submit/
---

Without a permalink, a page at _pages/about.md generates /about (no trailing slash). Set permalink: /about/ explicitly for consistency.

Permalinks for collections

Collections get their permalink pattern in _config.yml under the collection definition:

collections:
  themes:
    output: true
    permalink: /themes/:name/
  authors:
    output: true
    permalink: /authors/:name/

For a file _themes/minimal-mistakes.md, this generates /themes/minimal-mistakes/.

Available placeholders for collections: :name (filename without extension), :path, :output_ext, :title, :categories.

# Custom collection permalink using title from front matter
collections:
  themes:
    output: true
    permalink: /themes/:title/

The :title placeholder in detail

:title uses the post or page title, converted to a URL-safe slug:

• Lowercase
• Spaces replaced with hyphens
• Special characters removed
• Accented characters transliterated (é → e)

Title: "Jekyll Front Matter: The Complete Guide!"
:title → "jekyll-front-matter-the-complete-guide"

If you want a different slug than the auto-generated one, set slug in front matter:

---
title: "Jekyll Front Matter: The Complete Guide!"
slug: jekyll-front-matter-guide
permalink: /blog/:slug/
---

This gives /blog/jekyll-front-matter-guide/ instead of the long auto-generated version.

The :categories placeholder

If posts have categories, :categories generates a nested URL:

---
categories: [Tutorial, Jekyll]
permalink: /:categories/:title/
---

Generates: /tutorial/jekyll/my-post/

If a post has no categories, :categories is omitted from the URL (Jekyll does not include the empty slash).

Warning: Using :categories in your permalink means changing a post’s category changes its URL — which breaks links and SEO. Avoid :categories in permalinks for blog posts. Use it only for intentional category-based URL structures.

Trailing slashes

Jekyll generates index.html inside a folder for trailing-slash URLs:

permalink: /about/
→ _site/about/index.html
→ served at https://example.com/about/

Without a trailing slash:

permalink: /about
→ _site/about.html
→ served at https://example.com/about

Use trailing slashes consistently. Mixing /about/ and /contact causes inconsistency and potential duplicate content. Most modern Jekyll sites use trailing slashes.

Redirect old URLs after changing permalinks

If you change a permalink on an existing post, the old URL breaks. Redirect it using jekyll-redirect-from:

# Gemfile
gem "jekyll-redirect-from"

---
layout: post
title: "My Post"
permalink: /blog/my-new-url/
redirect_from:
  - /2026/08/07/my-old-url/
  - /blog/my-old-url/
---

Jekyll generates redirect pages at the old URLs pointing to the new one. Essential for maintaining SEO when restructuring content.

Checking generated URLs

To see what URL Jekyll generates for each file, run a build and check the _site/ directory structure — it mirrors your URL structure exactly:

bundle exec jekyll build
find _site -name "index.html" | head -20

Or use jekyll serve and browse to check each URL manually.

Internal linking with the link tag

When linking between pages internally, use the {% link %} or {% post_url %} tag instead of hardcoding URLs — they account for baseurl and raise a build error if the target file does not exist:

<a href="{% link _posts/2026-08-07-my-post.md %}">My Post</a>
<a href="{% post_url 2026-08-07-my-post %}">My Post</a>

Both resolve to the post’s actual URL, whatever the permalink setting.

SEO implications of permalink structure

Keyword in URL: Shorter URLs that include the post’s main keyword perform slightly better. /blog/jekyll-permalinks/ is better than /blog/jekyll-permalinks-and-url-structure-the-complete-guide-2026/.

Avoid dates unless meaningful: /blog/2026/08/07/my-post/ makes content look dated. /blog/my-post/ is evergreen.

Be consistent: Changing URL structure after publishing harms SEO even with redirects. Choose a structure you can live with long-term before publishing.

Use hyphens, not underscores: Google treats hyphens as word separators in URLs. my-post is two words; my_post is one. Use hyphens.

Short is better: The shorter and more descriptive the URL, the better. Remove stop words (the, a, an, and, or) from slugs when they add no meaning.

A complete permalink setup

Here is a solid permalink configuration for a Jekyll blog/marketplace:

# _config.yml

# Blog posts
permalink: /blog/:title/

# Collections
collections:
  themes:
    output: true
    permalink: /themes/:name/
  authors:
    output: true
    permalink: /authors/:name/

Pages set their own permalink in front matter:

# _pages/themes.md
permalink: /themes/

# _pages/about.md
permalink: /about/

# _pages/blog.md (blog index)
permalink: /blog/

This gives a clean, consistent URL structure where /blog/ contains posts, /themes/ contains theme pages, and top-level paths handle static pages.

Permalink strategies for SEO

Your permalink structure is one of the most consequential SEO decisions you make for a Jekyll site. URLs are visible in search results, shared on social media, cited in external links, and remembered by returning visitors. A well-designed permalink structure is clean, descriptive, and stable — changing it after your site has inbound links or search rankings is expensive.

The most SEO-friendly permalink format for blog posts is the title-only slug: /blog/jekyll-seo-guide/ rather than /blog/2025/12/16/jekyll-seo-guide/. Title-based slugs communicate the topic of the page to both users and search engines, they do not expose the publication date (which can make older content feel stale), and they are significantly shorter which makes them easier to share and remember. In _config.yml, set this with permalink: /blog/:title/.

Date-based URLs have legitimate uses for news sites and blogs where publication date is a meaningful signal — a political news site where “today’s coverage” matters is better served by /news/2025/12/16/story-title/ than by /news/story-title/. For evergreen technical content, tutorial sites, and theme marketplaces, date-based URLs are usually a liability rather than an asset.

Include the primary keyword in the slug where it appears naturally. A post titled “How to Install a Jekyll Theme on macOS” has the slug how-to-install-a-jekyll-theme-on-macos by default — which is appropriate. Do not stuff additional keywords into slugs; the post title’s natural keywords are sufficient. Very long slugs (over 60 characters) can be shortened by removing stop words: how-to-install-a-jekyll-theme-on-macos becomes install-jekyll-theme-macos without losing keyword meaning.

Managing permalink changes and redirects

When you change a permalink — whether for a single post or by changing the global permalink: format — you must redirect the old URL to the new one to preserve inbound links and avoid 404 errors. Each 404 on a URL that previously had inbound links is a lost backlink; over time, accumulating 404s from permalink changes can meaningfully reduce your domain authority.

For Netlify-hosted Jekyll sites, the _redirects file in your repository root handles redirects at the CDN level with zero latency: add old/url/ new/url/ 301 for a permanent redirect. For Cloudflare Pages, the same syntax works. For GitHub Pages, a jekyll-redirect-from plugin adds a redirect HTML page at the old URL that meta-refreshes to the new one — less clean than a true server-side redirect, but functional.

Set up Google Search Console and monitor the Coverage report after any permalink change. Search Console shows 404 errors with the inbound links that were trying to reach them — a direct map of which old URLs need redirects. Resolving these 404s promptly, within days of the permalink change, minimises the time during which inbound link authority is not being passed to the new URL.

Canonical URLs and duplicate content

Jekyll sites can inadvertently create duplicate content if multiple URLs serve the same or similar content. A blog post accessible at both /blog/post-title/ and /blog/post-title (with and without trailing slash) is a duplicate content risk if both URLs are indexed. Configure your Jekyll site to consistently redirect one format to the other — most hosts handle this with a redirect rule, and the jekyll-seo-tag plugin’s canonical_url output in the <head> tells search engines which version is authoritative.

Paginated archives are another potential duplicate content source. The first page of your blog at /blog/ and the paginated version at /blog/page/1/ may serve identical content. Configure your paginator to only generate /blog/page/2/ onwards, making /blog/ itself the first page — this is the default behaviour of jekyll-paginate-v2 but worth verifying in your specific theme.

Tag and category pages can create near-duplicate content when a single post appears on multiple archive pages with the same excerpt. Use noindex carefully — you generally want category and tag pages indexed so they rank for their topic keywords — but ensure your theme generates distinct, topic-appropriate titles and descriptions for each archive page rather than repeating generic metadata.

Verifying your permalink structure works

After configuring your permalink structure, test it before publishing extensively. Build your site locally with bundle exec jekyll build and browse the _site/ directory to verify that posts are being generated at the expected paths. Check a few edge cases: a post title with special characters (apostrophes, colons, question marks) that might produce unexpected slugs; posts in subdirectories of _posts/; and any posts with custom permalink: in their front matter that should override the global setting.

Use the jekyll-link-checker gem or an HTML proofer tool to scan your built site for internal broken links before deploying. Internal 404s from misconfigured links or incorrect link tags are easy to introduce and easy to miss without automated checking. A clean link check before each major deployment — especially after changing the permalink structure — is a low-cost insurance policy against broken internal navigation.

Permalink design is a low-visibility decision with long-lasting consequences — once you publish URLs, changing them breaks inbound links, social shares, and search rankings built up over time. Spend an hour deciding on your permalink structure before you publish your first post rather than months later dealing with the fallout of a necessary restructure. A date-free, category-organised slug like /blog/jekyll-collections-guide/ is the structure most likely to remain appropriate as your site grows and your content strategy evolves.

site variables

site contains global data about your Jekyll site — configuration from _config.yml, collections, posts, and build information.

Configuration variables

Every key in _config.yml becomes a site.* variable:

# _config.yml
title: "JekyllHub"
author: "Marcus Webb"
description: "A Jekyll theme marketplace."
url: "https://jekyllhub.com"
baseurl: ""
google_analytics: "G-XXXXXXXXXX"
sendy_list_id: "abc123"

{{ site.title }}           → "JekyllHub"
{{ site.description }}     → "A Jekyll theme marketplace."
{{ site.url }}             → "https://jekyllhub.com"
{{ site.baseurl }}         → ""
{{ site.author }}          → "Marcus Webb"
{{ site.google_analytics }}→ "G-XXXXXXXXXX"
{{ site.sendy_list_id }}   → "abc123"

Built-in site variables

These are provided by Jekyll itself, not from _config.yml:

site.posts

{% comment %} All posts, newest first {% endcomment %}
{% for post in site.posts %}
  <a href="{{ post.url }}">{{ post.title }}</a>
{% endfor %}

{% comment %} Post count {% endcomment %}
{{ site.posts | size }} posts

{% comment %} Latest post {% endcomment %}
{% assign latest = site.posts | first %}
{{ latest.title }}

site.pages

{% for page in site.pages %}
  {% if page.title %}
    <a href="{{ page.url }}">{{ page.title }}</a>
  {% endif %}
{% endfor %}

Note: site.pages includes all pages — HTML files, Markdown files, and some generated files. Filter by page.layout or page.url if you need a subset.

site.data

Mirrors the _data/ directory structure:

_data/
├── navigation.yml
├── authors.yml
└── showcase/
    └── sites.yml

{{ site.data.navigation }}         → contents of navigation.yml
{{ site.data.authors }}            → contents of authors.yml
{{ site.data.showcase.sites }}     → contents of showcase/sites.yml

site.categories and site.tags

{% comment %} Loop over all categories {% endcomment %}
{% for category in site.categories %}
  <h2>{{ category[0] }}</h2>          ← category name
  {% for post in category[1] %}
    <li>{{ post.title }}</li>          ← posts in this category
  {% endfor %}
{% endfor %}

{% comment %} Posts in a specific category {% endcomment %}
{% assign tutorial_posts = site.categories["Tutorial"] %}
{{ tutorial_posts | size }} tutorials

Collection variables

For a collection named themes (defined in _config.yml):

{{ site.themes }}                 → array of all theme documents
{{ site.themes | size }}          → number of themes
{% for theme in site.themes %}
  {{ theme.title }}
{% endfor %}

page variables

page contains data about the current page, post, or collection document being rendered.

Built-in page variables

Custom front matter variables

Every key in a page’s front matter becomes a page.* variable:

---
layout: post
title: "My Post"
author: Marcus Webb
featured: true
reading_time: 8
image: /assets/images/blog/cover.webp
difficulty: beginner
---

{{ page.author }}         → "Marcus Webb"
{{ page.featured }}       → true
{{ page.reading_time }}   → 8
{{ page.image }}          → "/assets/images/blog/cover.webp"
{{ page.difficulty }}     → "beginner"

page.url vs page.id

{{ page.url }}   → "/blog/jekyll-variables-reference/"
{{ page.id }}    → "/2026/08/06/jekyll-variables-reference"

page.url is the clean URL visitors see. page.id is an internal identifier used by some plugins.

page.date

{{ page.date }}                          → 2026-08-06 00:00:00 +0000
{{ page.date | date: "%B %-d, %Y" }}    → August 6, 2026
{{ page.date | date: "%Y-%m-%d" }}      → 2026-08-06
{{ page.date | date: "%s" }}            → Unix timestamp

page.excerpt

{{ page.excerpt }}              → first paragraph (rendered HTML)
{{ page.excerpt | strip_html }} → plain text excerpt
{{ page.excerpt | strip_html | truncatewords: 30 }}

Override the default excerpt in front matter:

excerpt: "A custom summary for this post."

page.next and page.previous

Navigate between posts:

{% if page.next %}
  <a href="{{ page.next.url }}">Next: {{ page.next.title }}</a>
{% endif %}
{% if page.previous %}
  <a href="{{ page.previous.url }}">Previous: {{ page.previous.title }}</a>
{% endif %}

Note: page.next is the chronologically newer post; page.previous is the older one — counterintuitive but correct.

page.categories and page.tags

{% for category in page.categories %}
  <a href="/category/{{ category | slugify }}/">{{ category }}</a>
{% endfor %}

{% for tag in page.tags %}
  <span class="tag">{{ tag }}</span>
{% endfor %}

layout variables

layout contains data from the current layout file’s front matter:

<!-- _layouts/post.html -->
---
layout: default
sidebar: true
show_related: true
---

{{ layout.sidebar }}      → true
{{ layout.show_related }} → true

Useful when a layout needs configuration that individual pages can check:

{% if layout.sidebar %}
  {% include sidebar.html %}
{% endif %}

content

Available only inside layout files. Contains the rendered HTML content being wrapped by the layout:

<!-- _layouts/default.html -->
<main>
  {{ content }}
</main>

content is the output after all inner layouts have been applied. For a post using layout: post (which itself uses layout: default), by the time default.html sees content, it already contains the post’s HTML wrapped in post.html’s structure.

paginator variables

Available on paginated pages when using jekyll-paginate or jekyll-paginate-v2:

{% for post in paginator.posts %}
  <article>
    <h2><a href="{{ post.url }}">{{ post.title }}</a></h2>
  </article>
{% endfor %}

<nav class="pagination">
  {% if paginator.previous_page %}
    <a href="{{ paginator.previous_page_path }}">← Newer</a>
  {% endif %}
  <span>Page {{ paginator.page }} of {{ paginator.total_pages }}</span>
  {% if paginator.next_page %}
    <a href="{{ paginator.next_page_path }}">Older →</a>
  {% endif %}
</nav>

jekyll variables

Information about the Jekyll build environment:

{{ jekyll.environment }}   → "development" or "production"
{{ jekyll.version }}       → "4.3.2"

{% if jekyll.environment == "production" %}
  {% include analytics.html %}
{% endif %}

Set JEKYLL_ENV=production before building to enable production-only features.

forloop variables

Inside any {% for %} loop:

{% for post in site.posts %}
  {{ forloop.index }}    → 1, 2, 3... (1-based)
  {{ forloop.index0 }}   → 0, 1, 2... (0-based)
  {{ forloop.rindex }}   → counts down from total (1-based)
  {{ forloop.rindex0 }}  → counts down from total (0-based)
  {{ forloop.first }}    → true on first iteration
  {{ forloop.last }}     → true on last iteration
  {{ forloop.length }}   → total items in array
{% endfor %}

Practical use — add a class to the first item and a divider between items:

{% for item in list %}
  <div class="item{% if forloop.first %} item--first{% endif %}">
    {{ item.name }}
  </div>
  {% unless forloop.last %}<hr>{% endunless %}
{% endfor %}

tablerow variables

Inside a {% tablerow %} loop:

{% tablerow item in list cols: 3 %}
  {{ tablerowloop.index }}
  {{ tablerowloop.col }}       → current column (1-based)
  {{ tablerowloop.col0 }}      → current column (0-based)
  {{ tablerowloop.col_first }} → true on first column
  {{ tablerowloop.col_last }}  → true on last column
  {{ tablerowloop.row }}       → current row number
  {{ tablerowloop.first }}     → true on first item
  {{ tablerowloop.last }}      → true on last item
  {{ tablerowloop.length }}    → total items
{% endtablerow %}

Quick reference: which variable to use

Using variables with Liquid filters

Jekyll variables become genuinely useful when combined with Liquid’s filter pipeline. Filters transform the raw variable output into something formatted for display or logic.

Formatting dates

{{ page.date | date: "%B %-d, %Y" }}      → "January 29, 2026"
{{ page.date | date: "%Y-%m-%d" }}         → "2026-01-29"
{{ page.date | date_to_xmlschema }}         → "2026-01-29T00:00:00+00:00"
{{ page.date | date_to_rfc822 }}            → RFC 822 format for RSS feeds

Generating slugs and URLs

{{ page.title | slugify }}                  → "jekyll-variables-reference"
{{ page.url | absolute_url }}               → "https://example.com/blog/post/"
{{ page.url | relative_url }}               → "/blog/post/"

Truncating and stripping content

{{ page.excerpt | strip_html }}             → plain text excerpt
{{ page.excerpt | truncatewords: 30 }}      → first 30 words
{{ page.content | strip_html | size }}      → character count of plain text
{{ page.title | upcase }}                   → uppercase title
{{ page.title | downcase | slugify }}       → normalised slug

Working with arrays

{{ site.posts | size }}                     → total post count
{{ site.posts | first }}                    → most recent post object
{{ site.posts | last }}                     → oldest post object
{{ page.tags | join: ", " }}               → "jekyll, tutorial, sass"
{{ site.posts | sort: "title" }}            → posts sorted alphabetically
{{ site.posts | where: "featured", true }}  → only featured posts
{{ site.posts | where_exp: "post", "post.tags contains 'jekyll'" }}

Debugging variables with inspect

When a template produces unexpected output, the inspect filter reveals the raw structure of any variable:

{{ page | inspect }}       → shows all page variables and their values
{{ site.data | inspect }}  → shows the complete data structure
{{ page.tags | inspect }}  → shows the tags array: ["jekyll", "tutorial"]

For complex nested objects, you can iterate to inspect individual keys:

{% for item in page %}
  {{ item[0] }}: {{ item[1] | inspect }}
{% endfor %}

This prints every key-value pair in the page object, which is invaluable when a theme expects a front matter variable you are not providing or uses a variable name different from what you assumed.

Variables inside includes

When you call {% include file.html %}, you can pass parameters that become available as include.parameter_name inside the included file:

{% include card.html title=post.title url=post.url image=post.image %}

Inside _includes/card.html:

<div class="card">
  <img src="{{ include.image }}" alt="{{ include.title }}">
  <a href="{{ include.url }}">{{ include.title }}</a>
</div>

The include variable is scoped to the included file and is not accessible outside it. This scoping keeps includes self-contained — they do not bleed state into the calling template.

You can also pass Liquid expressions and variables as include parameters:

{% include card.html title=page.title url=page.url | relative_url %}

Checking whether a variable is defined

Use the nil check to guard against undefined front matter variables:

{% if page.image %}
  <img src="{{ page.image }}" alt="{{ page.title }}">
{% endif %}

{% if page.author %}
  <span>By {{ page.author }}</span>
{% else %}
  <span>By {{ site.author }}</span>
{% endif %}

Use the default filter to provide a fallback value inline:

{{ page.author | default: site.author }}
{{ page.image | default: site.default_image }}
{{ page.description | default: site.description }}

The default filter returns the specified value when the original is nil, false, or an empty string. This is the cleanest way to implement fallback behaviour without {% if %} blocks.

Building a complete post template with variables

Putting variables together into a realistic post layout shows how they interact:

---
layout: default
---

<article
  class="post"
  itemscope
  itemtype="https://schema.org/BlogPosting"
>
  <header class="post-header">
    <div class="post-meta">
      <time datetime="{{ page.date | date_to_xmlschema }}" itemprop="datePublished">
        {{ page.date | date: "%B %-d, %Y" }}
      </time>
      {% if page.last_modified_at %}
        <time datetime="{{ page.last_modified_at | date_to_xmlschema }}" itemprop="dateModified">
          Updated {{ page.last_modified_at | date: "%B %-d, %Y" }}
        </time>
      {% endif %}
      {% for category in page.categories %}
        <a href="/category/{{ category | slugify }}/" class="category-link">
          {{ category }}
        </a>
      {% endfor %}
    </div>

    <h1 itemprop="headline">{{ page.title }}</h1>

    {% if page.description %}
      <p class="post-description" itemprop="description">{{ page.description }}</p>
    {% endif %}

    {% if page.author %}
      <div class="post-author" itemprop="author" itemscope itemtype="https://schema.org/Person">
        <span itemprop="name">{{ page.author }}</span>
      </div>
    {% endif %}

    {% if page.image %}
      <img
        src="{{ page.image | relative_url }}"
        alt="{{ page.title }}"
        itemprop="image"
        class="post-hero"
      >
    {% endif %}
  </header>

  <div class="post-content" itemprop="articleBody">
    {{ content }}
  </div>

  <footer class="post-footer">
    {% if page.tags.size > 0 %}
      <div class="post-tags">
        {% for tag in page.tags %}
          <a href="/tag/{{ tag | slugify }}/" class="tag">{{ tag }}</a>
        {% endfor %}
      </div>
    {% endif %}

    <nav class="post-nav" aria-label="Post navigation">
      {% if page.previous %}
        <a href="{{ page.previous.url }}" class="post-nav__prev">
          ← {{ page.previous.title }}
        </a>
      {% endif %}
      {% if page.next %}
        <a href="{{ page.next.url }}" class="post-nav__next">
          {{ page.next.title }} →
        </a>
      {% endif %}
    </nav>
  </footer>
</article>

This template uses page.date, page.last_modified_at, page.categories, page.title, page.description, page.author, page.image, content, page.tags, page.previous, and page.next — the full set of standard variables that any well-structured post file provides.

Common pitfalls with Jekyll variables

Forgetting that site.posts is sorted newest-first. If you want oldest-first, use {{ site.posts | reverse }}.

Confusing page.url with page.id. The URL is what you use in links; the ID is an internal reference used by some plugins. They look similar but are not interchangeable.

Using page.content inside the post layout. In layout files, use content (no page. prefix) to get the rendered HTML. page.content gives you the raw Markdown source, which is rarely what you want.

Accessing collection variables before declaring the collection. If site.projects returns nil, check that projects is declared under collections: in _config.yml and that the _projects/ directory exists.

Expecting forloop.first to detect the first post in site.posts. The forloop variable is scoped to the current {% for %} loop iteration. It does not know anything about the global list of posts — it only knows its position in the current loop run.

Keeping this variable reference bookmarked saves time whenever you are building or debugging a Jekyll template. The full list of built-in variables is also documented in the official Jekyll docs with additional detail on edge cases.

Variables in collection documents

Collection documents have all the standard page.* variables plus some collection-specific ones. When you loop over site.themes (a collection), each item exposes:

{{ theme.collection }}   → "themes" (the collection name)
{{ theme.relative_path }} → "_themes/minimal-mistakes.md"
{{ theme.path }}          → full filesystem path
{{ theme.url }}           → "/themes/minimal-mistakes/"
{{ theme.id }}            → "/themes/minimal-mistakes"
{{ theme.title }}         → from front matter
{{ theme.content }}       → rendered HTML body

All front matter fields on the document also become available as variables, so a theme document with stars: 27000 exposes theme.stars. This is the basis of filtering and sorting collection documents:

{% assign popular = site.themes | where_exp: "t", "t.stars > 10000" | sort: "stars" | reverse %}
{% for theme in popular limit: 6 %}
  <a href="{{ theme.url }}">{{ theme.title }} — ★ {{ theme.stars }}</a>
{% endfor %}

Generating variables at build time

Some variables cannot come from a static Markdown file — they need to be computed at build time. Jekyll’s plugin system lets you generate data and expose it through site.* or front matter variables during the build.

For example, to add a site.build_time variable that contains the formatted build timestamp:

# _plugins/build_time.rb
Jekyll::Hooks.register :site, :after_init do |site|
  site.config['build_time'] = Time.now.strftime('%Y-%m-%d %H:%M')
end

After adding this plugin, {{ site.build_time }} is available in every template.

A more common use case is reading data from external sources during the build — an API response, a JSON file, or a generated data file — and making it available as site.data.something. The _data/ directory supports this natively without plugins: any YAML, JSON, CSV, or TSV file in _data/ becomes accessible as site.data.filename.

The scope of each variable type

Understanding the scope of each variable type prevents a common class of bugs in Jekyll templates.

site variables are global — the same values are available in every layout, include, and page throughout the entire build. Changing a site.* variable in one template does not affect others (Liquid is stateless), but reading from it in any file always returns the same value.

page variables are page-scoped — they represent the current document being rendered. When Jekyll renders _posts/my-post.md using _layouts/post.html, the page variable inside both files refers to the same post document. When a layout includes a partial ({% include sidebar.html %}), the page variable inside the include still refers to the same document — not the include file itself.

layout variables are layout-scoped — they come from the front matter of the current layout file, not the page. This is a subtle distinction: if a page uses layout: post and post.html uses layout: default, then within default.html, the layout variable holds the front matter from default.html, and page still holds the page’s front matter.

include variables are include-scoped — parameters passed via {% include file.html param="value" %} are available as include.param only inside that include file, not in calling templates or other includes.

The mental model: site is the broadest scope (the whole build), page is mid-scope (the current document), layout is the current wrapper, and include parameters are the narrowest (one function call).

Keeping this hierarchy clear while reading or debugging templates makes it much easier to understand why a variable holds the value it does and where to go to change it.

Extending variables with custom plugins

For advanced use cases, Jekyll’s plugin system lets you add custom variables that are not available by default. This is useful for computed values, external API data, or dynamic configuration.

Adding custom site-level variables

# _plugins/site_extensions.rb
module Jekyll
  class SiteExtensions
    def self.extend(site)
      # Add a formatted build date
      site.config['build_date'] = Time.now.strftime('%B %-d, %Y')
      
      # Count published posts
      site.config['post_count'] = site.posts.docs.select(&:published?).size
      
      # Count themes in a collection
      themes = site.collections['themes']
      site.config['theme_count'] = themes ? themes.docs.size : 0
    end
  end
end

Jekyll::Hooks.register :site, :post_read do |site|
  SiteExtensions.extend(site)
end

After adding this plugin, you can use {{ site.build_date }}, {{ site.post_count }}, and {{ site.theme_count }} in any template — values computed once at build time and available everywhere.

Adding custom page-level variables

For per-page computed values, use a page hook that runs after front matter is read:

# _plugins/reading_time.rb
Jekyll::Hooks.register [:posts, :pages], :post_convert do |page|
  word_count = page.content.split.size
  reading_time = [(word_count / 200.0).ceil, 1].max
  page.data['reading_time'] = reading_time
end

This makes {{ page.reading_time }} available on every post and page, computed from the actual word count rather than requiring you to set it manually in front matter.

Custom variables created by plugins follow the same scoping rules as front matter variables — site.your_variable for site-level, page.your_variable for page-level — so they work seamlessly alongside standard Jekyll variables in any template.

Understanding all available variables and how to extend them gives you complete control over what data is available in your Jekyll templates, making it possible to build sophisticated themes and content structures without reaching for a dynamic backend.

Variables as the backbone of Jekyll templates

Every Jekyll template you write is fundamentally a question: what data do I have, and how do I transform and display it? Variables are the answers to that question. The more fluent you become with site.*, page.*, layout.*, and content, the faster you can build new templates and debug existing ones. The best way to develop this fluency is to read the templates of well-maintained open-source Jekyll themes — see how they handle missing values with defaults, how they construct URLs using relative_url, and how they combine variables with Liquid filters to produce clean, reliable output across every possible page configuration. Variables are the vocabulary; templates are the sentences. Mastering one makes the other straightforward.

Variables are well-documented in Jekyll’s official documentation at jekyllrb.com/docs/variables/, and that reference is worth keeping open when building templates. The official docs and this reference together cover every variable you will encounter in day-to-day Jekyll development.

A good Jekyll theme does the opposite: it is designed to be used, extended, and maintained — not just previewed. Here is what to look for before you commit.

Clean, Readable Liquid Templates

Open the theme’s _layouts/ and _includes/ directories on GitHub and read a few files. Well-written Liquid templates are:

Modular — the layout is broken into includes (_includes/header.html, _includes/footer.html, _includes/head.html) rather than crammed into one monolithic default.html. This makes it possible to override a single component without copying the entire layout.

Commented where it matters — complex Liquid logic (conditional includes, data lookups, paginator handling) should have a brief comment explaining what it does. Templates without any comments are harder to customise correctly.

Free of hard-coded content — good themes use _config.yml variables for site name, author, social links, and colour settings. A theme with your branding written directly into templates requires manual find-and-replace to customise.

Consistent naming conventions — front matter fields should follow a pattern (title, description, image, author) rather than an idiosyncratic mix that requires reading every template to understand.

Well-Organised SCSS

SCSS structure reveals a lot about how seriously a theme was built. A good Jekyll theme organises styles using:

Variables for everything visual — colours, font sizes, spacing, border radii, and breakpoints should all be defined as SCSS variables or CSS custom properties at the top of the stylesheet. This means you can retheme the entire site by changing a handful of values.

Logical file structure — styles split into logical partials: _variables.scss, _base.scss, _typography.scss, _layout.scss, _components.scss. A single style.scss file with 3,000 lines of undifferentiated CSS is a red flag.

No !important overuse — !important is sometimes necessary, but a theme that uses it everywhere is fighting its own specificity and will be painful to customise.

Dark mode handled properly — if the theme supports dark mode, it should use CSS custom properties swapped via a [data-theme="dark"] attribute or prefers-color-scheme media query, not a separate stylesheet loaded with JavaScript.

Performance by Default

A static site has no excuse to be slow. Before buying or installing a theme, check what it loads:

Minimal JavaScript — a blog or portfolio theme should need almost no JavaScript. If a theme loads jQuery, multiple animation libraries, and a carousel script for a site that displays text and images, those are unnecessary dependencies you will carry forever.

Self-hosted or system fonts — themes that load Google Fonts make an external request on every page load. A well-optimised theme either uses system fonts (font-family: system-ui, sans-serif) or bundles the fonts locally with font-display: swap.

Optimised images in templates — check the image includes. Does the theme use loading="lazy" on below-the-fold images? Does it specify width and height attributes to prevent layout shift?

No render-blocking resources — CSS should be in the <head>, JavaScript should be deferred or at the end of <body>. Check the source of the demo — a <script> tag without defer or async in the <head> will block every page from rendering.

Run Lighthouse on the live demo. A good Jekyll theme should score above 90 on Performance with no effort on your part — the theme itself should not be the bottleneck.

SEO Ready Out of the Box

A well-built Jekyll theme handles SEO fundamentals automatically:

jekyll-seo-tag integration — the theme should include {% seo %} in _layouts/default.html or equivalent. This handles title tags, meta descriptions, Open Graph, Twitter cards, and canonical URLs with a single include.

Proper heading hierarchy — one <h1> per page (the post or page title), with <h2> through <h4> used for content structure. A theme that wraps the site name in an <h1> on every page is hurting your SEO on every post.

RSS feed — the theme should include a <link rel="alternate" type="application/rss+xml"> in the head, pointing to a feed generated by jekyll-feed.

Structured data support — better themes include JSON-LD structured data for articles, breadcrumbs, or site links. This is not required, but it is a sign of a theme built with search visibility in mind.

Clean URLs — the theme should not produce URLs with .html extensions or unnecessary parameters. Jekyll handles this with permalink: pretty in _config.yml — check that the theme’s config sets this or documents how to do it.

Accessibility That Is Not an Afterthought

Accessibility in a theme is not just about compliance — it is about code quality. Themes that are accessible are also better structured, more maintainable, and more usable for everyone.

Semantic HTML — content should use <article>, <nav>, <main>, <aside>, and <footer> appropriately. A theme built entirely with <div> elements is not just inaccessible — it is lazy.

Skip navigation link — a “Skip to content” link as the first focusable element lets keyboard users bypass the navigation on every page. It is one line of HTML and CSS. Themes without it have not thought about keyboard navigation.

ARIA labels on interactive elements — icon-only buttons (like a dark mode toggle or search icon) need aria-label attributes to be usable by screen readers.

Focus styles — pressing Tab through the live demo should show a visible focus ring on every interactive element. Themes that remove focus styles with outline: none fail basic keyboard accessibility.

Colour contrast — body text on its background should meet WCAG AA (4.5:1 ratio minimum). Check this with the browser’s accessibility panel or a contrast checker.

Active Maintenance and a Clear Update History

Even the best theme becomes a liability if it is abandoned. Signs of a well-maintained theme:

A changelog — a CHANGELOG.md or release notes on GitHub showing what changed in each version. This tells you the author thinks carefully about changes and communicates them clearly.

Regular releases — at least a few updates in the past year. Check the releases page on GitHub, not just the commit history.

Responsive issue handling — open the GitHub issues and look for how the author responds to bug reports. Are bugs acknowledged and fixed? Or are issues sitting unanswered for months?

A versioning scheme — themes that use semantic versioning (1.2.0, 1.2.1) signal that the author understands the difference between a breaking change and a patch.

Good Documentation

Documentation is a direct measure of how much the author cares about the people using their theme.

A well-documented Jekyll theme covers:

• Quick start — how to get the theme running locally in five minutes
• Configuration reference — every _config.yml option explained with example values
• Front matter fields — what each layout accepts and what is required vs optional
• Customisation guide — how to override layouts, styles, and includes without editing theme source files
• Deployment notes — any hosting-specific configuration required
• Upgrade guide — what to do when a new version is released

If the only documentation is a README with a screenshot and a “fork this repo” instruction, the author has not thought about the experience of people actually using the theme.

The Quality Checklist

Use this before buying or installing any Jekyll theme:

Code quality

• Templates are modular (split into _includes/)
• No hard-coded content — everything comes from _config.yml or front matter
• SCSS uses variables for colours, fonts, and spacing
• No excessive !important usage
• Dark mode uses CSS custom properties, not a separate stylesheet

Performance

• Lighthouse performance score above 90 on the live demo
• No unnecessary JavaScript libraries
• Fonts are self-hosted or use system fonts
• Images use loading="lazy" and have width/height attributes
• No render-blocking scripts in <head>

SEO

• Includes jekyll-seo-tag
• One <h1> per page
• RSS feed linked in <head>
• Clean URLs (no .html extensions)

Accessibility

• Uses semantic HTML elements (<article>, <nav>, <main>)
• Has a skip navigation link
• Icon buttons have aria-label attributes
• Focus styles are visible
• Body text passes WCAG AA contrast (4.5:1)

Maintenance

• Last commit within 12 months
• Has a changelog or release notes
• Issues are responded to within a reasonable time
• Compatible with Jekyll 4.x

Documentation

• Quick start guide works
• Configuration options are documented
• Front matter fields are documented
• Customisation without editing source files is explained

A theme that scores well on all five areas — code, performance, SEO, accessibility, and maintenance — is genuinely worth using. Most themes will excel in one or two and be mediocre in others. The checklist helps you make that trade-off consciously rather than discovering it after you have built your site.

Ready to find a theme that meets this standard? Browse the JekyllHub theme directory — every theme is hand-reviewed for quality before listing.

Version compatibility and future-proofing

A quality Jekyll theme declares its Ruby and Jekyll version requirements clearly. Look for a Gemfile or gemspec that specifies a minimum Jekyll version (jekyll ">= 4.2"). Themes that still list Jekyll 3.x as the target have not been maintained for several years and will accumulate compatibility warnings as Ruby and Jekyll evolve.

Check that the theme uses Sass in a way compatible with Jekyll’s built-in processor, or explicitly requires the jekyll-sass-converter version it was developed against. Sass changed significantly between versions 1.x and 2.x, and themes that use deprecated @import patterns without acknowledgement of this fact are a sign of an unmaintained project.

The broader test: does the author show awareness of the Jekyll ecosystem as it exists today — GitHub Actions for deployment, modern Sass conventions, Jekyll 4.x configuration syntax? Themes built and maintained with current knowledge are substantially more valuable than those frozen in 2019.

assign

Creates a variable and assigns it a value. The variable is available for the rest of the template (or until overwritten).

{% assign title = "My Post" %}
{% assign count = site.posts | size %}
{% assign is_premium = false %}
{% assign tags_list = "jekyll,tutorial,liquid" | split: "," %}

Variables created with assign are available in the current scope and any includes called from it.

{% assign author = site.authors | where: "name", page.author | first %}
{% if author %}
  <img src="{{ author.avatar }}" alt="{{ author.name }}">
{% endif %}

capture

Builds a string variable from a block of content — useful when the value spans multiple lines or includes Liquid expressions.

{% capture post_url %}{{ site.url }}{{ post.url }}{% endcapture %}
<meta property="og:url" content="{{ post_url }}">

{% capture author_bio %}
  {{ page.author }} · {{ page.date | date: "%B %-d, %Y" }} · {{ page.reading_time }} min read
{% endcapture %}
<p class="post-meta">{{ author_bio | strip }}</p>

Unlike assign, capture captures everything between its opening and closing tags, including whitespace and newlines. Use | strip to remove leading/trailing whitespace.

if / elsif / else / endif

Conditional rendering. Outputs content only when the condition is true.

{% if page.price == 0 %}
  <span class="badge">Free</span>
{% elsif page.price < 20 %}
  <span class="badge">Budget</span>
{% else %}
  <span class="badge">Premium</span>
{% endif %}

Conditions can use:

• == equal to
• != not equal to
• > >= < <= numeric comparisons
• contains string/array contains
• and both conditions true
• or either condition true

{% if page.tags contains "jekyll" and page.featured %}
  This is a featured Jekyll post.
{% endif %}

{% if user.name == "admin" or user.role == "editor" %}
  Show edit button
{% endif %}

Truthy/falsy: In Liquid, nil and false are falsy. Everything else — including 0, "", and [] — is truthy. This differs from many other languages.

{% if page.image %}      ← false only if image is nil (not set) or false
{% if page.count > 0 %}  ← more reliable check for zero

unless / endunless

The inverse of if — runs the block when the condition is false. Equivalent to {% if not condition %}.

{% unless page.hide_sidebar %}
  {% include sidebar.html %}
{% endunless %}

{% unless forloop.last %}
  <hr>
{% endunless %}

case / when / else / endcase

Multi-branch conditional, cleaner than a long if/elsif chain when checking a single variable against multiple values.

{% case page.category %}
  {% when "Tutorial" %}
    <span class="badge badge--blue">Tutorial</span>
  {% when "Comparison" %}
    <span class="badge badge--purple">Comparison</span>
  {% when "Themes", "Design" %}
    <span class="badge badge--green">Design</span>
  {% else %}
    <span class="badge">Article</span>
{% endcase %}

Multiple values for the same branch: {% when "Themes", "Design" %} matches either.

for / endfor

Loops over an array or range. One of the most-used tags in Jekyll templates.

{% for post in site.posts %}
  <article>
    <h2><a href="{{ post.url }}">{{ post.title }}</a></h2>
    <p>{{ post.excerpt | strip_html | truncatewords: 25 }}</p>
  </article>
{% endfor %}

Loop parameters

{% comment %} First 6 posts {% endcomment %}
{% for post in site.posts limit: 6 %}

{% comment %} Skip the first 3 {% endcomment %}
{% for post in site.posts offset: 3 %}

{% comment %} Reverse order {% endcomment %}
{% for post in site.posts reversed %}

{% comment %} Combine: posts 4-9 {% endcomment %}
{% for post in site.posts limit: 6 offset: 3 %}

forloop variables

Inside a loop, these special variables describe the current iteration:

{% for post in site.posts %}
  {% if forloop.first %}<ul>{% endif %}
  <li class="{% if forloop.last %}last{% endif %}">
    {{ forloop.index }}.  {{ post.title }}
  </li>
  {% if forloop.last %}</ul>{% endif %}
{% endfor %}

else in for loops

Runs when the array is empty:

{% for theme in site.themes %}
  <div class="theme-card">{{ theme.title }}</div>
{% else %}
  <p>No themes available yet.</p>
{% endfor %}

Looping over a number range

{% for i in (1..5) %}
  <span>Step {{ i }}</span>
{% endfor %}

Nested loops

{% for category in site.categories %}
  <h2>{{ category[0] }}</h2>
  {% for post in category[1] %}
    <a href="{{ post.url }}">{{ post.title }}</a>
  {% endfor %}
{% endfor %}

break and continue

Control loop execution:

{% comment %} Stop after finding first featured post {% endcomment %}
{% for post in site.posts %}
  {% if post.featured %}
    <a href="{{ post.url }}">{{ post.title }}</a>
    {% break %}
  {% endif %}
{% endfor %}

{% comment %} Skip drafts in a custom loop {% endcomment %}
{% for post in site.posts %}
  {% unless post.published %}{% continue %}{% endunless %}
  <li>{{ post.title }}</li>
{% endfor %}

include

Inserts the contents of a file from _includes/. One of the most-used tags in Jekyll layouts.

{% include nav.html %}
{% include footer.html %}
{% include components/card.html %}

include with parameters

Pass variables to an include using key=value pairs:

{% include components/card.html
   title=theme.title
   url=theme.url
   price=theme.price
   image=theme.card_image %}

Inside the include, access them with include.keyname:

<!-- _includes/components/card.html -->
<div class="card">
  <h3>{{ include.title }}</h3>
  <a href="{{ include.url }}">View</a>
</div>

include with a variable filename

{% assign template = "components/card.html" %}
{% include {{ template }} %}

Or use include_relative to include from a path relative to the current file:

{% include_relative ../shared/notice.html %}

raw / endraw

Prevents Liquid from processing the enclosed content. Essential when writing Liquid code in blog posts.

  Use {{ variable }} syntax to output values.
  {% if condition %}...{% endif %}

Everything inside ... is output literally, without Liquid processing.

comment / endcomment

Adds a Liquid comment — not rendered in output and not processed:

{% comment %}
  TODO: add pagination here
  This section is temporarily disabled
{% endcomment %}

Unlike HTML comments (<!-- -->), Liquid comments are completely removed from output and cannot be seen by users in the page source.

highlight / endhighlight

Syntax-highlights a code block using Rouge:

{% highlight ruby %}
def hello
  puts "Hello, Jekyll!"
end
{% endhighlight %}

{% highlight javascript linenos %}
const site = "JekyllHub";
console.log(site);
{% endhighlight %}

The optional linenos adds line numbers. The language identifier must be one Rouge supports (ruby, javascript, python, bash, yaml, html, css, json, etc.).

link and post_url

Generate correct URLs for internal pages and posts, accounting for baseurl:

{% comment %} Link to a page (fails build if page not found) {% endcomment %}
<a href="{% link _pages/about.md %}">About</a>
<a href="{% link _posts/2026-08-03-jekyll-directory-structure.md %}">Read post</a>

{% comment %} Link to a post by filename {% endcomment %}
<a href="{% post_url 2026-08-03-jekyll-directory-structure %}">Read post</a>

Both link and post_url cause a build error if the target file does not exist — useful for catching broken internal links. They automatically apply baseurl.

tablerow

Like for, but generates an HTML table:

<table>
  {% tablerow plugin in site.data.plugins cols: 3 %}
    <td>{{ plugin.name }}</td>
  {% endtablerow %}
</table>

cols: sets the number of columns per row. Less commonly used than for, but useful for tabular data.

jekyll_draft and jekyll_version

Available in Jekyll 4+:

{% comment %} Show content only when serving with --drafts flag {% endcomment %}
{% if jekyll.environment == "development" %}
  <div class="draft-banner">Draft preview</div>
{% endif %}

Whitespace control

Liquid tags add blank lines to output. Strip whitespace with -:

{%- assign foo = "bar" -%}
{%- for item in list -%}
  {{ item }}
{%- endfor -%}

The - inside the tag delimiters strips whitespace (including newlines) before or after that tag. Use this when generating clean HTML or JSON output.

Tags vs filters: the difference

People sometimes confuse tags and filters. The distinction:

• Tags ({% %}) execute logic — they control flow, assign variables, loop, include files
• Filters (|) transform values — they modify the output of {{ }} expressions

{% assign count = site.posts | size %}   ← tag with filter in the value
{{ page.title | upcase }}                ← output with filter
{% for post in site.posts %}             ← loop tag

Knowing both tags and filters — and which is which — gives you the full toolkit for working with any Jekyll theme.

Why tags matter for Jekyll theme development

Every Jekyll theme is built on Liquid tags. When you open a layout file like _layouts/default.html or an include like _includes/header.html, you are reading a template that uses a combination of tags and filters to transform data into HTML. Understanding each tag at this level lets you read and modify any theme’s templates without guesswork.

The most common tags in production themes are if, for, include, assign, and capture. These five account for the majority of the logic in any Jekyll template. The others — unless, case, raw, comment, highlight, link, and post_url — appear regularly but less frequently.

A key insight for working with tags: they are processed at build time, not at runtime in the browser. Everything inside {% for %} loops and {% if %} conditions is evaluated once when Jekyll builds the site, and the resulting HTML is fixed. There is no re-execution in the browser. This is what makes Jekyll sites fast — no template processing happens when a visitor loads a page — and it is also what defines the boundary between Liquid (build-time) and JavaScript (runtime).

Debugging tag logic

When a Liquid tag produces unexpected output, a few diagnostic techniques are reliable.

The {{ variable | inspect }} output tag (which is not a tag but a filter, confusingly) prints the raw structure of any variable. Use it to confirm what a variable contains before passing it to a loop or condition:

{% assign author = site.authors | where: "name", page.author | first %}
<!-- Debug: -->
{{ author | inspect }}
<!-- Expected output: {"name"=>"Marcus Webb", "avatar"=>"/assets/...", ...} -->

For loop debugging, confirm the array is not empty before looping:

{% if site.themes == empty %}
  <!-- No themes found -->
{% else %}
  Found {{ site.themes | size }} themes
  {% for theme in site.themes %}
    {{ theme.title }}
  {% endfor %}
{% endif %}

For assign debugging, check that the variable name does not conflict with a Liquid keyword or a variable already defined in the scope. Liquid variables are case-sensitive — author and Author are different variables.

For include debugging, verify the file path is relative to _includes/. {% include nav.html %} looks for _includes/nav.html. {% include components/nav.html %} looks for _includes/components/nav.html. File not found silently outputs nothing in older Jekyll versions; newer versions throw a build error.

Combining tags for common patterns

Real templates combine tags into patterns that appear repeatedly across themes.

Conditional include with data lookup:

{% if page.author %}
  {% assign author_data = site.data.authors | where: "name", page.author | first %}
  {% if author_data %}
    {% include author-card.html author=author_data %}
  {% endif %}
{% endif %}

Paginated loop with empty state:

{% assign posts = site.posts | where: "category", page.category %}
{% if posts == empty %}
  <p>No posts in this category yet.</p>
{% else %}
  {% for post in posts limit: 12 %}
    {% include post-card.html post=post %}
  {% endfor %}
{% endif %}

Accumulated string with capture:

{% capture breadcrumbs %}
  <nav aria-label="Breadcrumb">
    <ol>
      <li><a href="/">Home</a></li>
      {% for category in page.categories %}
        <li><a href="/category/{{ category | slugify }}/">{{ category }}</a></li>
      {% endfor %}
      <li aria-current="page">{{ page.title }}</li>
    </ol>
  </nav>
{% endcapture %}
{{ breadcrumbs }}

The capture pattern is useful when you need to build HTML conditionally, store it in a variable, and either render it in a different part of the page or pass it as a parameter to an include.

Loop with separator (no trailing comma):

{% for tag in page.tags %}{{ tag }}{% unless forloop.last %}, {% endunless %}{% endfor %}