Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/osteele/gojekyll
A fast Go implementation of the Jekyll blogging engine
https://github.com/osteele/gojekyll
blog-engine cli golang jekyll liquid static-site-generator
Last synced: 5 days ago
JSON representation
A fast Go implementation of the Jekyll blogging engine
- Host: GitHub
- URL: https://github.com/osteele/gojekyll
- Owner: osteele
- License: mit
- Created: 2017-06-11T22:59:13.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2024-10-17T18:06:53.000Z (about 1 month ago)
- Last Synced: 2024-10-20T00:32:00.594Z (about 1 month ago)
- Topics: blog-engine, cli, golang, jekyll, liquid, static-site-generator
- Language: Go
- Homepage:
- Size: 879 KB
- Stars: 332
- Watchers: 12
- Forks: 14
- Open Issues: 23
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Gojekyll
[](#contributors-)
[![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]
This project was created by Oliver Steele ([@osteele](https://github.com/osteele)), and is currently maintained by Daniil Gentili ([@danog](https://github.com/danog)).
Gojekyll is a partially-compatible clone of the [Jekyll](https://jekyllrb.com)
static site generator, written in the [Go](https://golang.org) programming
language. It provides `build` and `serve` commands, with directory watch and
live reload.
| | Gojekyll | Jekyll | Hugo |
| ----------------------- | ----------------------------------------- | ------ | ---------------------------- |
| Stable | | ✓ | ✓ |
| Fast | ✓
([~20×Jekyll](./docs/benchmarks.md)) | | ✓ |
| Template language | Liquid | Liquid | Go, Ace and Amber templates |
| SASS | ✓ | ✓ | ✓ |
| Jekyll compatibility | [partial](#current-limitations) | ✓ | |
| Plugins | [some](./docs/plugins.md) | yes | shortcodes, theme components |
| Windows support | ✓ | ✓ | ✓ |
| Implementation language | Go | Ruby | Go |
- [Usage](#usage)
- [Installation](#installation)
- [Docker](#docker)
- [Binary Downloads](#binary-downloads)
- [From Source](#from-source)
- [[Optional] Install command-line autocompletion](#optional-install-command-line-autocompletion)
- [Status](#status)
- [Current Limitations](#current-limitations)
- [Other Differences](#other-differences)
- [Feature Checklist](#feature-checklist)
- [Troubleshooting](#troubleshooting)
- [Contributors](#contributors)
- [Attribution](#attribution)
- [Related](#related)
- [License](#license)
## Usage
```bash
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`:
```bash
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:
```bash
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](https://github.com/osteele/gojekyll/releases).
2. Download the latest version of [dart-sass](https://github.com/sass/dart-sass/releases) and [add it to your PATH](https://katiek2.github.io/path-doc/), or see the [Sass website](https://katiek2.github.io/path-doc/) for full installation instructions.
3. [Optional] **Themes**. To use a theme, you need to install Ruby and
[bundler](http://bundler.io/). Create a `Gemfile` that lists the theme., and
run `bundle install`. The [Jekyll theme
instructions](https://jekyllrb.com/docs/themes/) provide more detail, and
should work for Gojekyll too.
### From Source
Pre-requisites:
1. **Install go** (1) via [Homebrew](https://brew.sh): `brew install go`; or (2)
[download](https://golang.org/doc/install#tarball).
2. See items (2-3) under [Binary Downloads](#binary-downloads), above.
Then run:
```bash
go install github.com/osteele/gojekyll@latest
```
## [Optional] Install command-line autocompletion
Add this to your `.bashrc` or `.zshrc`:
```bash
# 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](./docs/plugins.md) 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](https://kramdown.gettalong.org/syntax.html#attribute-list-definitions)
- [`markdown="span"`, `markdown="block"`](https://kramdown.gettalong.org/syntax.html#html-blocks)
- Markdown configuration options
Also see the [detailed status](#feature-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
bold` renders as bold. This behavior matches the [Markdown
spec](https://daringfireball.net/projects/markdown/syntax#html), 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
(ref))` 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](./docs/plugins.md)
- [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][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](https://allcontributors.org/docs/en/emoji-key)):
Oliver Steele
💻 🎨 📖 🤔 🚇 🚧 📆 👀 ⚠️
Bjørn Erik Pedersen
📖
Maurits van der Schee
💻
Daniil Gentili
💻
Cameron Elliott
🤔
This project follows the
[all-contributors](https://github.com/all-contributors/all-contributors)
specification. [Contributions of any kind welcome](./CONTRIBUTING.md)!
## Attribution
Gojekyll uses these libraries:
| Package | Author(s) | Usage | License |
| ------------------------------------------------------------------------------ | ------------------------------------------------ | ---------------------------------------------------------- | --------------------------------------- |
| [github.com/jaschaephraim/lrserver](https://github.com/jaschaephraim/lrserver) | Jascha Ephraim | Live Reload | MIT License |
| [github.com/kyokomi/emoji](https://github.com/kyokomi/emoji) | kyokomi | `jemoji` plugin emulation | MIT License |
| [github.com/osteele/liquid](https://github.com/osteele/liquid) | yours truly | Liquid processor | MIT License |
| [github.com/pkg/browser](https://github.com/pkg/browser) | [pkg](https://github.com/pkg) | `serve --open-url` option | BSD 2-clause "Simplified" License |
| [github.com/radovskyb/watcher](https://github.com/radovskyb/watcher) | Benjamin Radovsky | Polling file watch (`--force_polling`) | BSD 3-clause "New" or "Revised" License |
| [github.com/danog/blackfriday](https://github.com/danog/blackfriday) | Russ Ross, Daniil Gentili | Markdown processing | Simplified BSD License |
| [github.com/sass/dart-sass](https://github.com/sass/dart-sass) | Listed [here](https://github.com/sass/dart-sass) | The reference implementation of Sass, written in Dart. | MIT License |
| [github.com/tdewolff/minify](https://github.com/tdewolff/minify) | Taco de Wolff | CSS minimization | MIT License |
| [github.com/bep/godartsass](https://github.com/bep/godartsass) | Drew Wells | Go API backed by the native Dart Sass Embedded executable. | MIT License |
| [github.com/alecthomas/kingpin/v2](https://github.com/alecthomas/kingpin) | Alec Thomas | command-line arguments | MIT License |
| [github.com/alecthomas/chroma](https://github.com/alecthomas/chroma) | Alec Thomas | Syntax highlighter | MIT License |
| [gopkg.in/yaml.v2](https://github.com/go-yaml/yaml) | 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](https://jekyllrb.com/docs/templates/) | test cases | filter examples |
| `jekyll help` command | `gojekyll help` text | help text |
| [`jekyll-feed` plugin](https://github.com/jekyll/jekyll-feed) | plugin emulation | `feed.xml` template |
| [`jekyll-redirect-from` plugin](https://github.com/jekyll/jekyll-redirect-from) | plugin emulation | redirect page template |
| [`jekyll-sitemap` plugin](https://github.com/jekyll/jekyll-redirect-from) | plugin emulation | sitemap template |
| [`jekyll-seo-tag` plugin](https://github.com/jekyll/jekyll-redirect-from) | 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](https://commons.wikimedia.org/wiki/File:Gophercolor.jpg). It is used
under the [Creative Commons Attribution-Share Alike 3.0 Unported
license](https://creativecommons.org/licenses/by-sa/3.0/deed.en).
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](https://jekyllrb.com/docs/home/) were always open in at least one tab
during development.
## Related
[Hugo](https://gohugo.io) is the pre-eminent Go static site generator. It isn't
Jekyll-compatible (-), but it's highly polished, performant, and productized
(+++).
[Liquid](https://github.com/osteele/liquid) is a pure Go implementation of
Liquid templates. I created it in order to use in this project.
[Jekyll](https://jekyllrb.com), of course.
## 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