Gojekyll

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

	Gojekyll	Jekyll	Hugo
Stable		✓	✓
Fast	✓ (~20×Jekyll)		✓
Template language	Liquid	Liquid	Go, Ace and Amber templates
SASS	✓	✓	✓
Jekyll compatibility	partial	✓
Plugins	some	yes	shortcodes, theme components
Windows support		✓	✓
Implementation language	Go	Ruby	Go

• Usage
• Installation
  • Binary Downloads
  • From Source
• [Optional] Install command-line autocompletion
• Status
  • Current Limitations
  • Other Differences
  • Feature Checklist
• Troubleshooting
• Contributors
• Attribution
• Related
• License

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

Installation

Binary Downloads

1. Ubuntu (64-bit) and macOS binaries are available from the releases page.
2. [Optional] Themes. To use a theme, you need to install Ruby and bundler. Create a Gemfile that lists the theme., and run bundle install. The Jekyll theme instructions provide more detail, and should work for Gojekyll too.

From Source

Pre-requisites:

1. Install go (1) via Homebrew: brew install go; or (2) download.
2. See items (2-3) under Binary Downloads, above, for optional installations.

First-time install:

go get github.com/osteele/gojekyll

Update to the latest version:

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

[Optional] Install command-line autocompletion

Add this to your .bashrc or .zshrc:

# Bash:
eval "$(gojekyll --completion-script-bash)"
# Zsh:
eval "$(gojekyll --completion-script-zsh)"

Status

This project works on the GitHub Pages sites that I and other contributors care about. It looks credible on a spot-check of other Jekyll sites.

Current Limitations

Missing features:

• Pagination
• Windows compatibility
• Math
• Plugin system. (Some individual plugins are emulated.)
• Liquid filter sassify is not implemented
• Liquid is run in strict mode: undefined filters and variables are errors.
• Missing markdown features:
  • attribute lists
  • markdown="span", markdown="block"
  • Markdown configuration options

Also see the detailed status below.

Other Differences

These will probably not change:

By design:

• Plugins must be listed in the config file, not a Gemfile.
• The wrong type in a _config.yml file – for example, a list where a string is expected, or vice versa – is generally an error.
• Server live reload is always on.
• serve --watch (the default) reloads the _config.yml and data files too.
• serve generates pages on the fly; it doesn't write to the file system.
• Files are cached in /tmp/gojekyll-${USER}, not ./.sass-cache

Upstream:

• Markdown:
  • < and > inside markdown is interpreted as HTML. For example, This is <b>bold</b> renders as bold. This behavior matches the Markdown spec, but differs from Jekyll's default Kramdown processor.
  • The autogenerated id of a header that includes HTML is computed from the text of the title, ignoring its attributes. For example, the id of ## Title (<a href="https://example.com/path/to/details">ref</a>)) is #title-ref, not #title-https-example-path-to-details-ref.
  • Autogenerated header ids replace punctuation by the hyphens, rather than the empty string. For example, the id of ## Either/or is #either-or not #eitheror; the id of ## I'm Lucky is #i-m-lucky not #im-lucky.

Muzukashii:

• An extensible plugin mechanism – support for plugins that aren't compiled into the executable.

Feature Checklist

• Content
  • Front Matter
  • Posts
  • Static Files
  • Variables
  • Collections
  • Data Files
  • Assets
    • Coffeescript
    • Sass/SCSS
• Customization
  • Templates
    • Jekyll filters
      • scssify
      • everything else
    • Jekyll tags
  • Includes
  • Permalinks
  • Pagination
  • Plugins – partial; see here
  • Themes
  • Layouts
• Server
  • Directory watch
• Commands
  • build
    • --source, --destination, --drafts, --future, --unpublished
    • --incremental, --watch, --force_polling, JEKYLL_ENV=production
    • --baseurl, --config, --lsi
    • --limit-posts
  • clean
  • help
  • serve
    • --open-uri, --host, --port
    • --incremental, –watch, --force_polling
    • --baseurl, --config
    • --detach, --ssl-* – not planned
  • doctor, import, new, new-theme – not planned
• Windows

Troubleshooting

If the error is "403 API rate limit exceeded", you are probably building a repository that uses the jekyll-github-metadata gem. Try setting the JEKYLL_GITHUB_TOKEN, JEKYLL_GITHUB_TOKEN, or OCTOKIT_ACCESS_TOKEN environment variable to the value of a GitHub personal access token and trying again.

Contributors

Thanks goes to these wonderful people (emoji key):

Oliver Steele 💻 🎨 📖 🤔 🚇 🚧 📆 👀 ⚠️

Bjørn Erik Pedersen 📖

Maurits van der Schee 💻

Daniil Gentili 💻

Cameron Elliott 🤔

This project follows the all-contributors specification. Contributions of any kind welcome!

Attribution

Gojekyll uses these libraries:

Package	Author(s)	Usage	License
github.com/jaschaephraim/lrserver	Jascha Ephraim	Live Reload	MIT 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/radovskyb/watcher	Benjamin Radovsky	Polling file watch (--force_polling)	BSD 3-clause "New" or "Revised" 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/tdewolff/minify	Taco de Wolff	CSS minimization	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
github.com/alecthomas/chroma	Alec Thomas	Syntax highlighter	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 template documentation	test cases	filter examples
jekyll help command	gojekyll help text	help text
jekyll-feed plugin	plugin emulation	feed.xml template
jekyll-redirect-from plugin	plugin emulation	redirect page template
jekyll-sitemap plugin	plugin emulation	sitemap template
jekyll-seo-tag plugin	plugin emulation	feed template

The theme for in-browser error reporting was adapted from facebookincubator/create-react-app.

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 highly polished, performant, and productized (+++).

Liquid is a pure Go implementation of Liquid templates. I created it in order to use in this project.

Jekyll, of course.

License

MIT