DOCSEARCHbyAlgolia
Submit Docs

Jekyll Documentation

website·Indexed 32 days ago

https://jekyll.1px.run

Documentation for Jekyll, including guides on the Liquid templating language (types, filters, and whitespace control), the Jekyll Cache API for faster site generation, and information on the core team.

Tokens
71.8K
Snippets
465
Records
665
Agent score
53%

What's inside Jekyll

  1. Overview of Jekyll for static site generation

    Jekyll is a static site generator designed to convert plain text files into static websites and blogs. It can be self-hosted or used via GitHub Pages, which is natively built on Jekyll. To deploy a blog via GitHub Pages, a user simply needs to create a repository, apply basic configuration, and add content.

  2. Introduction to Liquid template language in Jekyll

    Jekyll uses the Liquid template language as its engine. Liquid allows for flexible template processing across template directories, layout files, and any .html or .md file. It enables the use of dynamic variables (such as page or site titles) directly within Markdown or HTML content.

  3. Overview of the Liquid Template Language

    Liquid is a secure, open-source template language written in Ruby and developed by Shopify. It is designed for flexible web applications and websites, allowing users to modify templates without executing arbitrary code on the server, which prevents malicious attacks. Key architectural features include a separation of compilation and rendering for high performance, and versatility for use in both web pages and email templates.

  4. Overview of Jekyll static site generation

    Jekyll is a static site generator that separates content from templates. It allows developers to build blogs and websites using Markdown, HTML, and TXT for content, and the Liquid templating language for layouts. Because it produces static files, it requires no database, reducing security risks like hacking or malware and eliminating the need for frequent software upgrades.

  5. Understand the role of Jekyll Affinity Team Captains

    Jekyll uses affinity teams to distribute the workload of triaging Issues and Pull Requests across specialized groups, preventing the @jekyll/core team from becoming a bottleneck. Team Captains act as maintainers for these specific teams, responsible for categorizing and evaluating community contributions within their domain.

  6. Jekyll 4.0.0 Feature Enhancements

    Key functional improvements in Jekyll 4.0.0 include:

    • Dependency Upgrades: kramdown upgraded to v2.x, jekyll-sass-converter upgraded to v2.x (Sassc + source maps), and i18n upgraded to v1.x.
    • Liquid Improvements: The relative_url filter is now merged into the link and post_url tags. The where filter can now detect nil and empty values, and the where_exp filter supports binary operators.
    • File Support: Added support for *.xhtml files and allows the .markdown extension for page templates.
    • Collections: Added support for custom sorting of collection documents.
    • Configuration: Automatic loading of _config.toml is now supported.

  7. Understand Gem-based themes in Jekyll

    Gem-based themes package assets, layouts, includes, and stylesheets within a Ruby Gem rather than directly in the project directory. This allows theme developers to push updates to RubyGems, which users can receive by updating the gem. When using a Gem-based theme, directories like assets, _data, _layouts, _includes, and _sass are managed by the Gem but are still processed by Jekyll during the build process.

  8. Configure Jekyll using files or CLI

    Jekyll allows for highly flexible build customization. Configuration can be managed in two primary ways: by defining options in a _config.yml or _config.toml file located in the project root directory, or by passing specific custom parameters directly via the jekyll command in the terminal.

  9. Understand Jekyll's core design philosophy

    Jekyll is guided by five key principles that influence its development and product decisions:

    1. No Magic (Transparency): Jekyll avoids "black box" operations. It only performs actions explicitly requested by the user, ensuring the build process is predictable and easy to understand without extensive documentation.
    2. Out-of-the-Box Experience: The goal is immediate usability. After installation, default settings for Markdown parsing and automatic rebuilding should satisfy most users without requiring complex initial configuration.
    3. Content First: The tool is designed to simplify web publishing, focusing on a positive experience for content creators to manage their material.
    4. Stability and Backward Compatibility: Jekyll prioritizes consistent builds over time. Breaking changes are avoided unless there is a clear practical necessity, and when they occur, a clear migration path is provided.
    5. Lightweight and Extensible: The core remains small, covering the majority of user needs. Additional features are implemented as plugins, supported by a scalable core API to encourage community contributions.
    gem install jekyll

  10. Understand Buddy's Jekyll build process

    Buddy operates by running Jekyll within an isolated jekyll/jekyll Docker image. It automatically executes the jekyll build command, and the resulting static files are placed in the /filesystem directory. From there, files can be deployed to FTP/SFTP or IaaS services. Users can extend the pipeline by adding custom commands, installing packages, running Selenium tests, or adding notifications (e.g., Slack).

  11. Extend Jekyll functionality using the Plugin System

    Jekyll provides a built-in plugin system that allows developers to add custom functionality to a website without modifying the Jekyll source code. Plugins can be enabled in safe mode by adding them to the whitelist key in the _config.yml file. The system supports several types of extensions: Generators (creating extra content), Converters (transforming markup languages), Commands (adding sub-commands to the jekyll executable), Liquid Tags, Liquid Filters, and Hooks (for fine-grained control over the build process).
    # _config.yml
whitelist: 
  - name_of_plugin

  12. Configure Jekyll for ARM64 macOS architecture

    Jekyll provides specific documentation and guidance for resolving installation and compatibility issues when running on macOS with ARM64 (Apple Silicon) architecture.