| title | intro | redirect_from | product | versions | topics | shortTitle | |||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
About GitHub Pages and Jekyll |
Jekyll is a static site generator with built-in support for {% data variables.product.prodname_pages %}. |
|
{% data reusables.gated-features.pages %} |
|
|
GitHub Pages & Jekyll |
Jekyll is a static site generator with built-in support for {% data variables.product.prodname_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 {% data variables.product.prodname_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 AUTOTITLE.
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 {% data variables.product.prodname_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: rougeBy default, Jekyll doesn't build files or folders that:
- Are located in a folder called
/node_modulesor/vendor - Start with
_,., or# - End with
~ - Are excluded by the
excludesetting in your configuration file
If you want Jekyll to process any of these files, you can use the include setting in your configuration file.
{% data reusables.pages.about-front-matter %}
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.
{% data reusables.pages.add-jekyll-theme %} For more information, see Themes in the Jekyll documentation.
{% ifversion fpt or ghec %} You can add a supported theme to your site on {% data variables.product.prodname_dotcom %}. For more information, see Supported themes on the {% data variables.product.prodname_pages %} site and Adding a theme to your {% data variables.product.prodname_pages %} site using Jekyll.
To use any other open source Jekyll theme hosted on {% data variables.product.prodname_dotcom %}, you can add the theme manually.{% else %} You can add a theme to your site manually.{% endif %} For more information, see{% ifversion fpt or ghec %} themes hosted on {% data variables.product.prodname_dotcom %} and{% else %} Supported themes on the {% data variables.product.prodname_pages %} site and{% endif %} AUTOTITLE.
You can override any of your theme's defaults by editing the theme's files. For more information, see your theme's documentation and Overriding your theme's defaults in the Jekyll documentation.
You can download or create Jekyll plugins to extend the functionality of Jekyll for your site. For example, the jemoji plugin lets you use {% data variables.product.prodname_dotcom %}-flavored emoji in any page on your site the same way you would on {% data variables.product.prodname_dotcom %}. For more information, see Plugins in the Jekyll documentation.
{% data variables.product.prodname_pages %} uses plugins that are enabled by default and cannot be disabled:
jekyll-coffeescriptjekyll-default-layoutjekyll-gistjekyll-github-metadatajekyll-optional-front-matterjekyll-paginatejekyll-readme-indexjekyll-titles-from-headingsjekyll-relative-links
You can enable additional plugins by adding the plugin's gem to the plugins setting in your _config.yml file. For more information, see Configuration in the Jekyll documentation.
For a list of supported plugins, see Dependency versions on the {% data variables.product.prodname_pages %} site. For usage information for a specific plugin, see the plugin's documentation.
Tip
You can make sure you're using the latest version of all plugins by keeping the {% data variables.product.prodname_pages %} gem updated. For more information, see AUTOTITLE and Dependency versions on the {% data variables.product.prodname_pages %} site.
{% data variables.product.prodname_pages %} cannot build sites using unsupported plugins. If you want to use unsupported plugins, generate your site locally and then push your site's static files to {% data variables.product.github %}.
To make your site easier to read, code snippets are highlighted on {% data variables.product.prodname_pages %} sites the same way they're highlighted on {% data variables.product.github %}. For more information about syntax highlighting, see AUTOTITLE.
By default, code blocks on your site will be highlighted by Jekyll. Jekyll uses the Rouge highlighter (which is compatible with Pygments). If you specify Pygments in your _config.yml file, Rouge will be used as the fallback instead. Jekyll cannot use any other syntax highlighter, and you'll get a page build warning if you specify another syntax highlighter in your _config.yml file. For more information, see AUTOTITLE.
Note
Rouge only recognizes lower-case language identifiers for fenced code blocks. For a list of supported languages, see Languages.
If you want to use another highlighter, such as highlight.js, you must disable Jekyll's syntax highlighting by updating your project's _config.yml file.
kramdown:
syntax_highlighter_opts:
disable : trueIf your theme doesn't include CSS for syntax highlighting, you can generate {% data variables.product.prodname_dotcom %}'s syntax highlighting CSS and add it to your project's style.css file.
rougify style github > style.css{% data reusables.pages.test-locally %}