jigyll

Jigyll

Jigyll is a fork of gojekyll, which was created by Oliver Steele (@osteele) and is maintained by Daniil Gentili (@danog). Jigyll is not affiliated with or endorsed by the original authors. All original work remains under their copyright; see LICENSE.

Jigyll 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
  • Homebrew (macOS / Linux)
  • Quick Install (macOS / Linux)
  • Docker
  • Binary Downloads
  • From Source
• [Optional] Install command-line autocompletion
• Development
• Status
  • Current Limitations
  • Other Differences
  • Feature Checklist
• Troubleshooting
• Contributors
• Attribution
• Related
• License

Usage

jigyll build       # builds the site in the current directory into _site
jigyll serve       # serve the app at http://localhost:4000; reload on changes
jigyll help
jigyll help build

Installation

Homebrew (macOS / Linux)

brew tap reidransom/tap
brew install jigyll

This pulls in dart-sass automatically, so SCSS/Sass works out of the box.

Quick Install (macOS / Linux)

The installer downloads the jigyll binary and, unless sass is already on your PATH, a matching Dart Sass:

curl -fsSL https://raw.githubusercontent.com/reidransom/jigyll/main/install.sh | sh

Pin a specific release with VERSION, or change the install location with INSTALL_DIR:

curl -fsSL https://raw.githubusercontent.com/reidransom/jigyll/main/install.sh | VERSION=v1.0.1 sh

Prefer to read before running? Download and inspect it first:

curl -fsSL https://raw.githubusercontent.com/reidransom/jigyll/main/install.sh -o install.sh
less install.sh && sh install.sh

Docker

You can use jigyll with the official reidransom/jigyll 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 reidransom/jigyll build -s /app

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

# Linux (host networking):
docker run --user $UID:$GID -v $PWD:/app --pull always --network host --rm -it reidransom/jigyll serve -s /app

On Docker Desktop (macOS / Windows), --network host does not reach the host, so publish the port and bind the server to all interfaces inside the container:

docker run --user $UID:$GID -v $PWD:/app --pull always -p 4000:4000 --rm -it reidransom/jigyll serve -s /app -H 0.0.0.0

Binary Downloads

1. Linux, Mac OS and Windows binaries for amd64, armv6/v7, armv8, riscv64 are available from the releases page. SCSS/Sass support requires the Dart Sass sass executable on your PATH (the Quick Install script sets this up for you; otherwise see From Source for how to install it).
2. [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 Jigyll too.

From Source

Pre-requisites:

1. Install go (1) via Homebrew: brew install go; or (2) download.
2. Install the Dart Sass executable:
   • On macOS: brew install sass/sass/sass
   • On Linux: see item (2) under Binary Downloads or install via your package manager.
3. See item (2) under Binary Downloads for theme support.

Then run:

go install github.com/reidransom/jigyll@latest

[Optional] Install command-line autocompletion

Add this to your .bashrc or .zshrc:

# Bash:
eval "$(jigyll --completion-script-bash)"
# Zsh:
eval "$(jigyll --completion-script-zsh)"

Development

This project uses just as a command runner. Run just to see available recipes:

just build      # compile the binary
just buildlinux # cross-compile for linux (amd64 + arm64)
just clean      # remove build artifacts
just install    # install the binary
just lint       # run linter
just release    # bump patch version, tag, and push
just test       # run tests

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 list definitions (ALDs, i.e. {:refname: .class} reusable sets; inline attribute lists {: .class #id} on headings are supported)
  • 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/jigyll-${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

Jigyll 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