Gojekyll

Gojekyll is a clone of the Jekyll static site generator, written in the Go programming language. It supports the build and serve commands, with directory watch and live reload.

I wrote this in order to learn Go. I was also hoping for faster preview of changes to GitHub Pages.

Gojekyll is incomplete, minimally tested, and doesn't run on Windows. It appears to be about twenty times faster than Jekyll, so that's something.

• Gojekyll
  • Installation
  • Usage
  • Status
    • Current Limitations
    • Other Differences
    • Feature Checklist
  • Contributing
  • Attribution
  • Related
  • License

Installation

First-time install:

1. Install go. (On macOS running Homebrew, brew install go is easier than the Install instructions on the Go site.)
2. go get osteele/gojekyll/cmd/gojekyll
3. To use the {% highlight %} tag, you also need Pygments. pip install Pygments.

Update to the latest version:

• go get -u github.com/osteele/liquid github.com/osteele/gojekyll/cmd/gojekyll

Usage

gojekyll build       # builds the site in the current directory into _site
gojekyll serve       # serve the app at http://localhost:4000; reload on changes
gojekyll help
gojekyll help build

Status

This project is at an early stage of development.

It works on the Google Pages sites that I care about, and it looks credible on a spot-check of other Jekyll sites.

It doesn't run on Windows, and it may not work for you.

In addition to the limitations listed below, this software isn't robust. Jekyll, Hugo, and other mature projects have lots of test coverage, and have had lots of testing by lots of people. I've this used only in limited ways, in the month since I started writing it.

Current Limitations

Missing features:

• Themes
• Excerpts
• Pagination
• Math
• CSV and JSON data files
• Plugins. (Some plugins are emulated. See the plugin board for their status.)
• Template filters group_by_exp, cgi_escape, uri_escape, and scssify
• More Liquid tags and filters, listed here.
• Markdown features: attribute lists, automatic ids, markdown=1.
• site.data is not sorted.
• Windows compatibility

Also see the detailed status below.

Other Differences

These will probably not change:

By design:

• serve generates pages on the fly; it doesn't write to the file system.
• Files are cached to /tmp/gojekyll-${USER}, not ./.sass-cache
• Server live reload is always on.
• serve --watch (the default) reloads _config.yml too.
• Jekyll provides an (undocumented) jekyll.version variable to templates. Copying this didn't seem right.
• Incremental build. The emphasis is on optimizing the non-incremental case. This is easier with fewer code paths.

Muzukashii:

• uniq on objects (things that aren't strings or numbers) doesn't work the way it does in Jekyll / Shopify Liquid. See the Go Liquid differences for more on this.
• An extensible plugin mechanism – support for plugins that aren't compiled into the executable.

Feature Checklist

• Content
  • Front Matter
  • Posts
    • Categories
    • Tags
    • Drafts
    • Future
    • Related
  • Static Files
  • Variables
  • Collections
  • Data Files
    • CSV
    • JSON
    • YAML
  • Assets
    • Coffeescript
    • Sass/SCSS
• Customization
  • Templates
    • Jekyll filters
      • group_by_exp, cgi_escape, uri_escape, scssify, smartify
      • everything else
    • Jekyll tags
      • include
      • include_relative
      • link
      • post_url
      • highlight
  • Includes
    • include parameters
    • include variables (e.g. {% include {{ expr }} %})
  • Permalinks
  • Pagination
  • Plugins
    • jekyll-avatar
    • jekyll-coffeescript
    • jekyll-gist (ignores noscript: false)
    • jekyll-live-reload (always on)
    • jekyll-paginate
  • Themes
  • Layouts
• Server
  • Directory watch
• Commands
  • build
    • --source, --destination, --drafts, --future, --unpublished
    • --config, --baseurl, --lsi, --no-watch
    • not planned: --force-polling, --limit-posts, --incremental, JEKYLL_ENV=production
  • clean
  • help
  • serve
    • --open-uri, --host, --port
    • --detach, --baseurl
    • not planned: --incremental, --ssl-*
  • not planned: doctor, import, new, new-theme
• Windows

Also see:

• The feature parity board board lists differences between Jekyll and gojekyll in more detail.
• The plugin board lists the implementation status of common plugins. (Gojekyll lacks an extensible plugin mechanism. The goal is to be able to use it to build Jekyll sites that use the most popular plugins.)
• The Go Liquid feature parity board to see differences between the real Liquid library and the one that is used in gojekyll.

Contributing

Bug reports, test cases, and code contributions are more than welcome. Please refer to the contribution guidelines.

Attribution

Gojekyll uses these libraries:

Package	Author(s)	Usage	License
github.com/jaschaephraim/lrserver	Jascha Ephraim	Live Reload	MIT License
github.com/dchest/cssmin	Dmitry Chestnykh	CSS minimization	BSD 3-clause "New" or "Revised" License
github.com/kyokomi/emoji	kyokomi	jemoji plugin emulation	MIT License
github.com/osteele/liquid	yours truly	Liquid processor	MIT License
github.com/pkg/browser	pkg	serve --open-url option	BSD 2-clause "Simplified" License
github.com/russross/blackfriday	Russ Ross	Markdown processing	Simplified BSD License
github.com/sass/libsass	Listed here	C port of the Ruby SASS compiler	MIT License
github.com/wellington/go-libsass	Drew Wells	Go bindings for libsass	???
gopkg.in/alecthomas/kingpin.v2	Alec Thomas	command-line arguments	MIT License
gopkg.in/yaml.v2	Canonical	YAML support	Apache License 2.0

In addition, the following pieces of text were taken from Jekyll and its plugins. They are used under the terms of the MIT License.

Source	Use	Description
jekyll help command	gojekyll help text	help text
Jekyll template documentation	test cases	filter examples
jekyll-feed plugin	plugin emulation	feed.xml template
jekyll-redirect-from plugin	plugin emulation	redirect page template

The gopher image in the testdata directory is from Wikimedia Commons. It is used under the Creative Commons Attribution-Share Alike 3.0 Unported license.

In addition to being totally and obviously inspired by Jekyll and its plugins, Jekyll's solid documentation was indispensible --- especially since I wanted to implement Jekyll as documented, not port its source code. The Jekyll docs were always open in at least one tab during development.

Related

Hugo is the pre-eminent Go static site generator. It isn't Jekyll-compatible (-), but it's extraordinarily polished, performant, and productized (+++).

jkl is another Go clone of Jekyll. If I'd found it sooner I might have started this project by forking that one. It's got a better name, too.

Liquid is a pure Go implementation of Liquid templates, that I finally caved and wrote in order to use in this project.

Jekyll, of course.

License

MIT