Test-driving some techniques for building static sites with Jekyll.
Jekyll is a simple, blog-aware, static site generator. It takes a template directory containing raw text files in various formats, runs it through a converter (like Markdown) and our Liquid renderer, and spits out a complete, ready-to-publish static website suitable for serving with your favorite web server.
Quickstart - Create and run a Template Site
See the quickstart guide.
gem install bundler jekyll jekyll new myblog cd myblog bundle jekyll serve open http://localhost:4000
Build & watch for changes
$ jekyll build --watch # => The current folder will be generated into ./_site, # watched for changes, and regenerated automatically.
GitHub Automatic Page Generator (deprecated)
The Automatic Page Generator is an old (deprecated) GitHub feature for generating a web site from a repository. This has now been replaced by Jekyll-based template. GitHub provide some migration support from the settings page.
The gh-pages-auto repo started with the Automatic Page Generator.
- gh-pages-auto GitHub Repo - repo originally built with the Automatic Page Generator
- gh-pages-auto web - how it appears when served by GitHub Pages
GitHub Pages - Simplified Publishing
Provided you work within the currently supported versions of Jekyll and related utilities, then publishing a web site from a GitHub repository can be a very simple process.
The blog post Publishing with GitHub Pages, now as easy as 1, 2, 3 describes the essentials.
- gh-pages-simple GitHub Repo - basic repo using implicit Jekyll page generation
- gh-pages-simple web - how it appears when served by GitHub Pages
GitHub Pages - Offline Publishing
One of the problems with using automatic GitHub Pages publishing is that you must accept the currently supported versions of Jekyll and related utilities.
If this is a deal-breaker, then an alternative is to build Jekyll pages offline using a custom mix of utilities. Then use GitHub Pages to serve the resulting site.
In gh-pages-offline I use a customised jekyll-readme-index gem that is not supported by GitHub Pages servers
- gh-pages-offline GitHub Repo - repo that uses offline generation
- gh-pages-offline web - how it appears when served by GitHub Pages
Themes and Templates
- Themes listing - from the jekyll wiki
- jekyllthemes.org - visual browser of submitted themes
- Adding a Jekyll theme to your GitHub Pages site
Basing a site on left is simply a matter of cloning the repo and customising as required:
- gh-pages-left GitHub Repo - repo for a site based on left
- gh-pages-left web - how it appears when served by GitHub Pages
All generated internal links are relative to the site root. This creates an issue on GitHub Pages since the default site root will be
The best way around this is to serve GitHub Pages on a custom URL, so the site works fine without any special modification when served on GitHub Pages and also when served locally with:
bundle exec jekyll build
Handling paths was improved with the
relative_url filter - see Jekyll 3.3 release notes.