Fork me on GitHub

Project Notes

#027

Test-driving some techniques for building static sites with Jekyll.

Notes

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

myblog

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.

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.

landing-gh-pages-simple

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

Themes and Templates

Left

Zach Holman published a starter-repo called left that provides all the scaffolding for a minimalist site. It is described in his blog post on left.

Basing a site on left is simply a matter of cloning the repo and customising as required:

Pixyll

A simple, beautiful Jekyll theme that’s mobile first pixyll.com, pixyll on GitHub.

Jekyll Tips

Relative Paths

All generated internal links are relative to the site root. This creates an issue on GitHub Pages since the default site root will be <org/username>.tardate.io/repository-name/.

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.

Credits and References

About LCK#27 Jekyllstatic

This page is a web-friendly rendering of my project notes shared in the LittleCodingKata GitHub repository.

Project Source on GitHub Return to the LittleCodingKata Catalog
About LittleCodingKata

LittleCodingKata is my collection of programming exercises, research and code toys broadly spanning things that relate to programming and software development (languages, frameworks and tools).

These range from the trivial to the complex and serious. Many are inspired by existing work and I'll note credits and references where applicable. The focus is quite scattered, as I variously work on things new and important in the moment, or go back to revisit things from the past.

This is primarily a personal collection for my own edification and learning, but anyone who stumbles by is welcome to borrow, steal or reference the work here. And if you spot errors or issues I'd really appreciate some feedback - create an issue, send me an email or even send a pull-request.

Follow the Blog follow projects and notes as they are published in your favourite feed reader