Jekyll is a simple, blog-focused static site generator. It combines your plain text content (such as Markdown files), template files (HTML, CSS, etc.), and some configuration to output a complete, ready-to-deploy static website.

Core Philosophy

  • Static: Jekyll generates pure HTML, CSS, and JavaScript files. This means that once the website is generated, there’s no need for server-side databases or dynamic scripting languages (like PHP, Python, Ruby) to process user requests. The server only needs to provide these pre-generated files.

  • Content-Driven: You primarily create content by writing plain text files (most commonly Markdown) rather than through complex admin interfaces.

  • Templating: Using the Liquid templating language, you can create reusable layouts and include fragments to maintain consistency in your website’s structure and appearance.

How It Works (Basic Process)

Input

You provide:

  • Content Files: Usually Markdown (.md) or HTML (.html) files containing your articles, pages, etc. These files typically include Front Matter.

  • Layout Files: HTML files that define the overall structure of pages (usually placed in the _layouts directory).

  • Include Files: Reusable HTML fragments such as headers, footers, and sidebars (usually placed in the _includes directory).

  • Data Files: YAML, JSON, CSV files for storing structured data (usually placed in the _data directory).

  • Assets: CSS, JavaScript, images, fonts, and other files (usually placed in the assets directory or specific folders in the root directory).

  • Configuration File: The _config.yml file containing global settings and plugin configurations for your site.

Processing

When you run the jekyll build or jekyll serve command, Jekyll:

  1. Reads the _config.yml file to get the configuration.
  2. Parses all content files, extracting metadata (like title, date, layout) from the Front Matter.
  3. Converts Markdown files to HTML.
  4. Uses the Liquid template engine to inject content into the specified layout files.
  5. Processes Includes, inserting them at the appropriate locations.
  6. Processes Data Files, making the data accessible in templates.
  7. Processes Sass/SCSS files (if used) and compiles them to CSS.
  8. Copies all static asset files.

Output

Jekyll places all processed and generated files into a folder, by default named _site. This _site folder contains the complete website that can be uploaded directly to any web server or static hosting platform (such as GitHub Pages, Netlify, Vercel, AWS S3).

Key Concepts in Detail

Front Matter

  • This is a YAML (or JSON) block at the top of each content file (articles, pages), wrapped in three dashes (---).
  • It’s used to define metadata for the file, such as layout, title, date, categories, tags, and any custom variables you need.

Example:

---
layout: post
title: "My First Blog Post"
date: 2023-10-27 10:00:00 +0800
categories: jekyll update
tags: [getting-started, tutorial]
custom_var: "Some custom information"
---

Here is the body of the article, written in Markdown…

Liquid Templating Language

Developed by Shopify, it’s Jekyll’s core rendering engine.

  • Objects/Variables: Output content, wrapped in double curly braces {{ }}. For example, {{ page.title }} outputs the title of the current page (defined in the Front Matter). {{ site.title }} outputs the site title defined in _config.yml.

  • Tags: Execute logic, wrapped in curly braces and percent signs {% %}. For example, {% for post in site.posts %} for looping through all posts, {% if page.show_sidebar %} for conditional logic, {% include header.html %} for including files.

  • Filters: Modify variable output, connected with a pipe symbol |. For example, {{ page.date | date: "%Y-%m-%d" }} formats the date, {{ "hello world" | capitalize }} outputs “Hello world”.

Directory Structure (Typical Conventions)

  • _config.yml: Configuration file.
  • _posts: Contains blog posts. Filenames must follow the YYYY-MM-DD-title.md (or .html) format. The date and title are extracted from the filename and can be used as metadata.
  • _drafts: Contains unpublished draft posts. They are included when running jekyll serve --drafts.
  • _layouts: Contains layout templates (like default.html, post.html, page.html).
  • _includes: Contains reusable code snippets (like header.html, footer.html).
  • _data: Contains data files (like members.yml, projects.json). Accessible via site.data.filename.
  • _site: Default output directory. Don’t manually edit files in this directory as they are regenerated with each build. You should add this directory to .gitignore.
  • assets (or other custom name): Contains CSS, JS, images, and other static resources.
  • index.md / index.html: The homepage of your website.
  • Other .md / .html files: Processed into individual pages (e.g., about.md generates about.html).

Collections

  • Beyond _posts, you can define your own content types. For example, you can create a _portfolio collection to manage your project portfolio.
  • Collections need to be defined in _config.yml, and you can specify whether they should output individual page files.

Themes

  • Jekyll supports theming, allowing you to package the appearance and structure of your website as a Ruby Gem.
  • This makes it easy to change your website’s appearance and share designs. You can specify theme: theme-name in _config.yml.

Plugins

  • You can extend Jekyll’s functionality through Ruby Gems.
  • Plugins can add new Liquid tags/filters, generate specific types of content (like Sitemaps), or add converters (supporting other markup languages).

Note: GitHub Pages has limited plugin support, running only a small set of security-certified plugins by default. If your project is hosted on GitHub Pages and needs custom plugins, you may need to build your site locally or through a CI/CD service (like GitHub Actions) and then push the generated _site directory contents to the deployment branch.

Advantages of Jekyll

  • Excellent Performance: Static files respond quickly, with no database queries or server-side rendering needed.
  • High Security: Small attack surface with no risk of database or dynamic script execution vulnerabilities.
  • Easy Version Control: All content and code are plain text files, perfect for version management and collaboration using Git.
  • Simple and Flexible Deployment: Can be deployed on virtually any web server, including many free or inexpensive static hosting services.
  • Good Scalability (Traffic-wise): Static files are easy to distribute via CDN, easily handling high traffic.
  • Complete Control: You have full control over the final HTML, CSS, and JavaScript.
  • Free and Open Source: No licensing fees required.

Disadvantages of Jekyll (or Points to Note)

  • Learning Curve: For non-technical users, there’s a need to learn Markdown, Front Matter, Liquid syntax, and basic command-line operations.
  • Build Time: For very large sites (thousands of pages), the build process can become slow.
  • Limited Dynamic Functionality: Dynamic features like comments, search, form submissions require third-party services (like Disqus, Algolia, Formspree) or custom JavaScript. Jekyll itself doesn’t handle these.
  • Non-Real-Time Preview (to some extent): Although jekyll serve provides a local server and auto-refresh, changes still go through a brief build process before you see the effects, unlike some WYSIWYG editors.
  • Ruby Environment Dependency: Installing and running Jekyll requires a local Ruby development environment, which can sometimes lead to configuration issues.

Common Use Cases

  • Personal blogs
  • Project documentation sites
  • Personal portfolio websites
  • Small business/organization promotional sites
  • Open source project websites (especially on GitHub Pages)

Summary

Jekyll is a powerful and flexible static site generator, particularly suitable for developers and tech enthusiasts who want to focus on content creation, need high performance and security, and don’t mind working with text files and command line. It enables efficient creation and maintenance of well-structured, consistently-designed static websites by separating content, templates, and configuration, and leveraging the Liquid templating language. While it has a learning curve and doesn’t directly provide dynamic functionality, its simplicity, performance, and version control advantages make it a very attractive choice in many scenarios.

Comments