gojekyll

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
  • 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 also need Pygments: pip install Pygments.
3. [Optional] Themes. To use a theme, you need to create a Gemfile that lists the theme, and run (the Ruby command) bundle install. The Jekyll theme instructions provides 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

[Later] Update to the latest version:

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

[Optional] Install command-line autocompletion:

# 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 are errors.
• Markdown features
  • Attribute lists
  • markdown="span", markdown="block"
• Markdown configuration options

Differences:

• The order of YAML maps, in _config and site.data, is not preserved.

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 is 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
• Markdown:
  • markdown=1 is only processed in Markdown files. This matches the Jekyll documentation, but not its implementation (which also expands markdown inside of markdown=1 elements inside *.html files).
  • < 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.

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
      • group_by_exp and 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
    • --baseurl, --config, --lsi, JEKYLL_ENV=production
    • --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

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