Topics

#blog-engine #cli #golang #jekyll #liquid #static-site-generator

Language breakdown

No language data available.

▸ Files click to expand

README

Gojekyll

[![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 | ✓
(~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 |

Usage
Installation

- Docker - Binary Downloads - From Source

[[Optional] Install command-line autocompletion](#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

Linux, Mac OS and Windows binaries for x86, amd64, armv6/v7, armv8, riscv64 are available from the releases

page.

Download the latest version of dart-sass and add it to your PATH, or see the Sass website for full installation instructions.
[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:

Install go (1) via Homebrew: brew install go; or (2)

download.

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 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, --forcepolling, JEKYLLENV=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 JEKYLLGITHUBTOKEN, JEKYLLGITHUBTOKEN, or OCTOKITACCESSTOKEN environment variable to the value of a [GitHub personal access token][personal-access-token] and trying again.

[personal-access-token]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

Contributors

Thanks goes to these wonderful people (emoji key):

_{Oliver Steele} 💻 🎨 📖 🤔 🚇 🚧 📆 👀 ⚠️	_{Bjørn Erik Pedersen} 📖	_{Maurits van der Schee} 💻	_{Daniil Gentili} 💻	_{Cameron Elliott} 🤔	_{Brian Smith} 💻	_Chimbori 💻
_{Max Bernstein} 🐛

This project follows the all-contributors specification. Contributions of any kind welcome!

Attribution

Gojekyll uses these libraries:

| Package | Author(s) | Usage | License | | ------------------------------------------------------------------------------ | ------------------------------------------------ | ---------------------------------------------------------- | --------------------------------------- | | github.com/jaschaephraim/lrserver | Jascha Ephraim | Live Reload | MIT License | | github.com/kyokomi/emoji | kyokomi | jemoji plugin emulation | MIT License | | github.com/osteele/liquid | yours truly | Liquid processor | MIT License | | github.com/pkg/browser | pkg | serve --open-url option | BSD 2-clause "Simplified" License | | github.com/radovskyb/watcher | Benjamin Radovsky | Polling file watch (--forcepolling) | BSD 3-clause "New" or "Revised" License | | github.com/danog/blackfriday | Russ Ross, Daniil Gentili | Markdown processing | Simplified BSD License | | github.com/sass/dart-sass | Listed here | The reference implementation of Sass, written in Dart. | MIT License | | github.com/tdewolff/minify | Taco de Wolff | CSS minimization | MIT License | | github.com/bep/godartsass | Drew Wells | Go API backed by the native Dart Sass Embedded executable. | MIT License | | github.com/alecthomas/kingpin/v2 | Alec Thomas | command-line arguments | MIT License | | github.com/alecthomas/chroma | Alec Thomas | Syntax highlighter | MIT License | | gopkg.in/yaml.v2 | Canonical | YAML support | Apache License 2.0 |

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

| Source | Use | Description | | ------------------------------------------------------------------------------- | -------------------- | ---------------------- | | Jekyll template documentation | test cases | filter examples | | jekyll help command | gojekyll help text | help text | | jekyll-feed plugin | plugin emulation | feed.xml template | | jekyll-redirect-from plugin | plugin emulation | redirect page template | | jekyll-sitemap plugin | plugin emulation | sitemap template | | jekyll-seo-tag plugin | plugin emulation | feed template |

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.

License

MIT

[coveralls-url]: https://coveralls.io/r/osteele/gojekyll [coveralls-svg]: https://img.shields.io/coveralls/osteele/gojekyll.svg?branch=master [license-url]: https://github.com/osteele/gojekyll/blob/master/LICENSE [license-svg]: https://img.shields.io/badge/license-MIT-blue.svg [go-url]: https://github.com/osteele/gojekyll/actions?query=workflow%3A%22Build+Status%22 [go-svg]: https://github.com/osteele/gojekyll/actions/workflows/go.yml/badge.svg [golangci-lint-url]: https://github.com/osteele/gojekyll/actions?query=workflow%3Agolangci-lint [golangci-lint-svg]: https://github.com/osteele/gojekyll/actions/workflows/golangci-lint.yml/badge.svg [go-report-card-url]: https://goreportcard.com/report/github.com/osteele/gojekyll [go-report-card-svg]: https://goreportcard.com/badge/github.com/osteele/gojekyll

🔗 More in this category