Gojekyll

<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->

<!-- ALL-CONTRIBUTORS-BADGE:END -->

[![go badge][go-svg]][go-url] [![Golangci-lint badge][golangci-lint-svg]][golangci-lint-url] [![Coveralls badge][coveralls-svg]][coveralls-url] [![Go Report Card badge][go-report-card-svg]][go-report-card-url] [![MIT License][license-svg]][license-url]

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 | ✓<br>(~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 |

<!-- TOC -->

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

<!-- /TOC -->

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.

Math Support

gojekyll supports mathematical expressions using MathJax or KaTeX, compatible with Jekyll/kramdown syntax:

• Use $$...$$ delimiters for both inline and display math
• Math expressions are preserved in the HTML output for client-side rendering
• Works with both MathJax 3 and KaTeX

Example usage:

Inline math: The equation $$E=mc^2$$ is famous.

Display math:
$$
\int_0^\infty e^{-x} dx = 1
$$

Setup: Add MathJax or KaTeX scripts to your layout templates. See example/_layouts/math.html and example/math-example.md for complete examples.

Current Limitations

Missing features:

• Pagination
• Plugin system. (Some individual plugins are emulated.)
• Liquid is run in strict mode: undefined filters and variables are errors.
• Missing markdown features:
  • attribute lists
  • 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 <b>bold</b>. 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
• [x] 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):

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --> <!-- prettier-ignore-start --> <!-- markdownlint-disable --> <table> <tr> <td align="center"><a href="https://code.osteele.com/"><img src="https://avatars.githubusercontent.com/u/674?v=4?s=100" width="100px;" alt=""/><br />_{<b>Oliver Steele</b>}</a><br /><a href="https://github.com/osteele/gojekyll/commits?author=osteele" title="Code">💻</a> <a href="#design-osteele" title="Design">🎨</a> <a href="https://github.com/osteele/gojekyll/commits?author=osteele" title="Documentation">📖</a> <a href="#ideas-osteele" title="Ideas, Planning, & Feedback">🤔</a> <a href="#infra-osteele" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="#maintenance-osteele" title="Maintenance">🚧</a> <a href="#projectManagement-osteele" title="Project Management">📆</a> <a href="https://github.com/osteele/gojekyll/pulls?q=is%3Apr+reviewed-by%3Aosteele" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/osteele/gojekyll/commits?author=osteele" title="Tests">⚠️</a></td> <td align="center"><a href="https://bep.is/"><img src="https://avatars.githubusercontent.com/u/394382?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Bjørn Erik Pedersen</b></su