Gojekyll

Gojekyll is a re-implementation of the Jekyll static site generator, in the Go programming language.

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

Installation

Install go. On macOS running Homebrew, brew install go is easier than the linked instructions.
go get -u osteele/gojekyll/cmd/gojekyll
You need Pygments in order use the {% highlight %} tag: pip install Pygments.

Usage

gojekyll build
gojekyll serve
gojekyll help
gojekyll help build

Limitations

Missing features:
- Themes
- Excerpts
- Pagination
- Math
- Warning mode
- Plugins, except jekyll-avatar and jekyll-gist
- Site variables: html_pages, html_files, and tags
- Jekyll filters: group_by_exp, pop, shift, cgi_escape, uri_escape, scssify, and smartify
- Some Liquid features. See Go Liquid README.
- CSV and JSON data files.
{% highlight %} uses Pygments. There's no way to tell it to use Rouge. Also, I don't know what will happen if Pygments isn't installed.
<div markdown=1> doesn't work. I think this is a limitation of the Blackfriday Markdown processor.
This is a very new code base. It probably panics or otherwise fails on a lot of legitimate constructs, and misbehaves on others.
Liquid errors aren't reported very nicely.
build with no -d option resolves the destination relative to the source directory, not the current directory.

Other Differences

These will probably not change.

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 (and the rest of the site) when that file changes.
An extensible plugin mechanism. Emulations of commonly-used plugins can be added to the repo.

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	6.85s
gojekyll	single-threaded; warm cache	0.61s
gojekyll	multi-threaded	0.34s

This isn't a fair comparison but 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 concurrency or the cache. They were switched off by re-building the executable to produce these timings.

In the multi-threaded case, whether the cache is warm or cold doesn't seem to matter.

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 pop shift 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, --watch, etc.
  - not planned: --force-polling, --limit-posts, --incremental, JEKYLL_ENV=production
- clean
- doctor
- help
- import
- new
- new-theme
- serve
  - --open-uri
  - --detach, --host, --port, --baseurl
  - not planned: --incremental, --ssl-*
Windows

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

In addition to being totally and obviously inspired by Jekyll, Jekyll's documentation was solid and indispensible. Many of the filter test cases are taken directly from the Jekyll documentation, and during development the Jekyll docs were always open in at least one tab.

The text for gojekyll help was taken from the output of jekyll help.

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.

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

8.8 KiB Raw Blame History