About GitHub Pages and Jekyll

Jekyll is a static site generator with built-in support for GitHub Pages.

Who can use this feature?

GitHub Pages is available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. See GitHub's plans.

In this article

Note

While the github-pages gem remains supported for some workflows, GitHub Actions is now the recommended approach for deploying and automating GitHub Pages sites.

About Jekyll

Jekyll is a static site generator with built-in support for GitHub Pages and a simplified build process. Jekyll takes Markdown and HTML files and creates a complete static website based on your choice of layouts. Jekyll supports Markdown and Liquid, a templating language that loads dynamic content on your site. For more information, see Jekyll.

Jekyll is not officially supported for Windows. For more information, see Jekyll on Windows in the Jekyll documentation.

We recommend using Jekyll with GitHub Pages. If you prefer, you can use other static site generators or customize your own build process locally or on another server. For more information, see Creating a GitHub Pages site.

Configuring Jekyll in your GitHub Pages site

You can configure most Jekyll settings, such as your site's theme and plugins, by editing your _config.yml file. For more information, see Configuration in the Jekyll documentation.

Some configuration settings cannot be changed for GitHub Pages sites.

lsi: false
safe: true
source: [your repo's top level directory]
incremental: false
highlighter: rouge
gist:
  noscript: false
kramdown:
  math_engine: mathjax
  syntax_highlighter: rouge

By default, Jekyll doesn't build files or folders that:

  • Are located in a folder called /node_modules or /vendor
  • Start with _, ., or #
  • End with ~
  • Are excluded by the exclude setting in your configuration file

If you want Jekyll to process any of these files, you can use the include setting in your configuration file.

Front matter

To set variables and metadata, such as a title and layout, for a page or post on your site, you can add YAML front matter to the top of any Markdown or HTML file. For more information, see Front Matter in the Jekyll documentation.

You can add site.github to a post or page to add any repository references metadata to your site. For more information, see Using site.github in the Jekyll Metadata documentation.

Themes

You can add a Jekyll theme to your GitHub Pages site to customize the look and feel of your site. For more information, see Themes in the Jekyll documentation.

You can add a supported theme to your site on GitHub. For more information, see Supported themes on the GitHub Pages site and