In addition to supporting regular HTML content, GitHub Pages supports Jekyll, a popular static site generator.
GitHub Pages is deeply integrated with Jekyll, a popular static site generator designed for blogging and software documentation, but used for much more. Jekyll makes it easy to create site-wide headers and footers without having to copy them across every page. It also offers advanced templating features and Jekyll theme support.
Although GitHub Pages was designed to work with any static site generator, using Jekyll offers a lot of built-in support and is the only static site generator GitHub Enterprise officially documents in detail. For more information on how you can use GitHub Pages with another static site generator, see "Using a static site generator other than Jekyll."
The main advantages of Jekyll are:
- You can use Markdown instead of HTML. Markdown is simpler to read and write.
- You can add a Jekyll theme to your site without copying CSS files.
- You can use common templates, such as headers and footers, that are shared across files.
- You can use a simplified build process to build your site with GitHub Pages.
Jekyll's build process
Jekyll's simplified build process with GitHub Pages is one of the biggest advantages of using Jekyll instead of other static site generators. GitHub Pages manages your site's build process with a single push to your site's publishing branch. This is Jekyll's build process for managing your site:
- Push file changes to your pages publishing branch
- GitHub Pages publishes your site.
Note: The publishing branch you use depends on the type of GitHub Pages site you have.
- For User or Organization pages, use the
masterbranch. - For Project pages, use the
gh-pagesormasterbranch. Alternatively, you can also publish your site from a/docsfolder on themasterbranch. For more information, see "Configuring a publishing source for GitHub Pages."
Jekyll site examples
Jekyll is the most commonly used static site generator for GitHub Pages. We recommend using Jekyll if you want the built-in support it offers, including the GitHub Pages gem to manage dependencies, specific build failure messages, and more specific help with troubleshooting.
These GitHub showcases include examples of Jekyll sites:
Further Reading
To learn more about Jekyll, see Jekyll's official documentation.
