gojekyll

Gojekyll

Gojekyll is a 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.

“It is easier to write an incorrect program than understand a correct one.” - Alan Perlis

Gojekyll is intended as an homage to Jekyll, and as a possible alternative in situations (such as iterative development of sites that don't use unsupported features) where speed is more important than total compatibility.

• Gojekyll
  • Usage
  • Installation
  • 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

Pre-requisites:

1. Install go (1) via Homebrew: brew install go; or (2) download.
2. [Optional] To use the {% highlight %} tag, you also need Pygments: pip install Pygments.

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:

• Themes
• Pagination
• Math
• Plugin system. (Some plugins are emulated.)
• Liquid filter sassify
• Markdown features: attribute lists, markdown=1.
• site.data is not sorted.
• Windows compatibility

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.
• Liquid is run in strict mode; undefined filters are errors.a
• 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
• Jekyll provides an (undocumented) jekyll.version variable to templates. Copying this didn't seem right.

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, --watch
    • --baseurl, --config, --incremental, --lsi
    • --force_polling, --limit-posts, JEKYLL_ENV=production – not planned
  • clean
  • help
  • serve
    • --open-uri, --host, --port, –watch (enabled by default)
    • --baseurl, --config, --incremental
    • --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