danog/gojekyll repository overview

⁠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.

• Usage⁠
• Installation⁠
  • Docker⁠
  • 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

⁠Docker

You can use gojekyll with the official danog/gojekyll image, for example to build the site in the current directory into _site:

docker run --user $UID:$GID -v $PWD:/app --pull always --rm -it danog/gojekyll build -s /app

Another example, serve the website in the current directory on http://localhost:4040, automatically reloading on changes:

docker run --user $UID:$GID -v $PWD:/app --pull always --network host --rm -it danog/gojekyll serve -s /app

⁠Binary Downloads

1. Linux, Mac OS and Windows binaries for x86, amd64, armv6/v7, armv8, riscv64 are available from the releases page⁠.
2. Download the latest version of dart-sass⁠ and add it to your PATH⁠, or see the Sass website⁠ for full installation instructions.
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.

Then run:

go install github.com/osteele/gojekyll@latest

⁠[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
• 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:

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

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

Jekyll⁠, of course.

⁠License

MIT