Gojekyll
This project was created by Oliver Steele (@osteele), and is currently maintained by Daniil Gentili (@danog).
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
- [Optional] Install command-line autocompletion
- Status
- 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 runbundle 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.
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
- Jekyll filters
- Includes
- Permalinks
- Pagination
- Plugins – partial; see here
- Themes
- Layouts
- Templates
- 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:
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 (--force_polling ) |
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.
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