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
  • Usage
  • Installation
    • Binary Downloads
    • From Source
  • [Optional] Install command-line autocompletion
  • Status
    • Current Limitations
    • Other Differences
    • Feature Checklist
  • Contributing
  • 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] Highlight. To use the {% highlight %} tag, you need Pygments: pip install Pygments.
3. [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 is at an early stage of development.

It works on the GitHub Pages sites that I care about, and 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
  • [x] Front Matter
  • [x] Posts
  • [x] Static Files
  • [x] Variables
  • [x] Collections
  • [x] Data Files
  • [ ] Assets
    • [ ] Coffeescript
    • [x] Sass/SCSS
• [ ] Customization
  • [x] Templates
    • [ ] Jekyll filters
      • [ ] scssify
      • [x] everything else
    • [x] Jekyll tags
  • [x] Includes
  • [x] Permalinks
  • [ ] Pagination
  • [ ] Plugins – partial; see here
  • [x] Themes
  • [x] Layouts
• [x] Server
  • [x] Directory watch
• [ ] Commands
  • [x] build
    • [x] --source, --destination, --drafts, --future, --unpublished
    • [x] --incremental, --watch, --force_polling, JEKYLL_ENV=production
    • [ ] --baseurl, --config, --lsi
    • [ ] --limit-posts
  • [x] clean
  • [x] help
  • [x] serve
    • [x] --open-uri, --host, --port
    • [x] --incremental, –watch, --force_polling
    • [ ] --baseurl, --config
    • [ ] --detach, --ssl-* – not planned
  • [ ] doctor, import, new, new-theme – not planned
• [ ] Windows

Contributing

Bug reports, test cases, and code contributions are more than welcome.

Attribution

Gojekyll uses these libraries:

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

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 (+++).

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.

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