Gojekyll

Gojekyll is a clone of the Jekyll static site generator, in the Go programming language.

• Gojekyll
  • Installation
  • Usage
  • Current Limitations
  • Other Differences
  • Timings
  • Feature Status
  • Contributing
  • Credits
  • Related
  • License

Installation

First-time install:

1. Install go. On macOS running Homebrew, brew install go is easier than the linked instructions.
2. go get osteele/gojekyll/cmd/gojekyll
3. To use the {% highlight %} tag, you 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
gojekyll help
gojekyll help build

Current Limitations

Missing features:

• Themes
• Excerpts
• Pagination
• Math
• CSV and JSON data files
• Plugins (except jekyll-avatar, jekyll-gist, and jekyll-redirect-from, which are simulated)
• site-static_files, site.html_files, and site.tags
• Jekyll liquid filters: group_by_exp, cgi_escape, uri_escape, scssify, and smartify
• Windows compatibility

For more detailed status:

• 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.

Other Differences

These will probably not change.

• uniq doesn't work the same way as in Jekyll / Shopify Liquid. See the Go Liquid differences for more on this.
• Real Jekyll provides an (undocumented) jekyll.version variable to templates. Copying this didn't seem right.
• 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.
• The server reloads the _config.yml too.
• An extensible plugin mechanism: support for plugins that aren't compiled into the executable.
• Incremental build isn't planned. The emphasis is on optimizing the non-incremental case.

Timings

[go]jekyll -s jekyll/docs build on a late-2015 MacBook Pro, running current versions of everything as of 2017-07-01.

Executable	Options	Time
jekyll		18.53s
gojekyll	single-threaded; cold cache	3.31s ± 0.07s
gojekyll	single-threaded; warm cache	2.50s ± 0.04s
gojekyll	multi-threaded	1.51s ± 0.01s
gojekyll	multi-threaded	0.80s ± 0.09s

This isn't an apples-to-ranges comparison. Gojekyll doesn't use all the plugins that Jekyll does. In particular, jekyll-mentions parses each page's HTML. This could slow Gojekyll down once it's added.

There's currently no way to disable the cache. It was disabled off by re-building the executable.

The cache is for calls to Pygments (via the highlight tag). For another site, SASS is greater overhead. This is another candidate for caching, but with multi-threading it may not matter.

Feature Status

• 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 - not planned

Contributing

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

Credits

Gojekyll uses these libraries:

Package	Author(s)	Description	License
github.com/jaschaephraim/lrserver	Jascha Ephraim	Live Reload server	MIT
github.com/osteele/liquid	yours truly	Liquid processor	MIT
github.com/pkg/browser	pkg	The serve -o option to open the site in the browser	BSD 2-clause "Simplified" License
github.com/russross/blackfriday	Russ Ross	Markdown processor	Simplified BSD License
github.com/sass/libsass	Listed here	C port of the Ruby SASS compiler	MIT
github.com/wellington/go-libsass	Drew Wells	Go bindings for libsass	???
gopkg.in/alecthomas/kingpin.v2	Alec Thomas	command line and flag parser	MIT
gopkg.in/yaml.v2	Canonical	YAML support	Apache License 2.0

The text for gojekyll help was taken from the output of jekyll help, and is used under the terms of the MIT license.

Many of the filter test cases are taken directly from the Jekyll documentation, and are used under the terms of the MIT license.

The template for jekyll-redirect-from emulation was adapted from the template in https://github.com/jekyll/jekyll-redirect-from, and is used under the terms of the MIT license.

The template for jekyll-feed emulation was taken verbatim from https://github.com/jekyll/jekyll-feed, and is used under the terms of the MIT license

https://github.com/jekyll/jekyll-feed/

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 documentation was solid and indispensible. During development the Jekyll docs were always open in at least one tab.

Related

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

Liquid is a Go implementation of Liquid templates. I wrote it for gojekyll, but it's implemented as a standalone library.

Jekyll, of course.

License

MIT