danog/gojekyll
1
0
Fork 0
mirror of https://github.com/danog/gojekyll.git synced 2024-12-02 12:37:49 +01:00
Code Issues Projects Releases Wiki Activity
4f60d74558
gojekyll/README.md
Bjørn Erik Pedersen 6d54e114fb
Update Hugo matrix in README
2019-02-05 23:36:47 +01:00

238 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Gojekyll
[![][travis-svg]][travis-url] [![][coveralls-svg]][coveralls-url] [![][go-report-card-svg]][go-report-card-url] [![][license-svg]][license-url]
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 | ✓<br>([~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 |
<!-- TOC -->
- [Gojekyll](#gojekyll)
- [Usage](#usage)
- [Installation](#installation)
- [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)
- [Contributing](#contributing)
- [Attribution](#attribution)
- [Related](#related)
- [License](#license)
<!-- /TOC -->
## 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
### Binary Downloads
1. Ubuntu (64-bit) and macOS binaries are available from the [releases page](https://github.com/osteele/gojekyll/releases).
2. [Optional] **Highlight**. To use the `{% highlight %}` tag, you need [Pygments](http://pygments.org): `pip install Pygments`.
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**, above, for optional installations.
First-time install:
```bash
go get github.com/osteele/gojekyll
```
Update to the latest version:
```bash
go get -u github.com/osteele/liquid github.com/osteele/gojekyll
```
## [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 is at an early stage of development.
It works on the GitHub Pages sites that I care about, and it looks credible on a spot-check of other Jekyll sites.
### Current Limitations
Missing features:
- Pagination
- Windows compatibility
- 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 <b>bold</b>` renders as <b>bold</b>. 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 (<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](./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
- [ ] Windows
## Contributing
Bug reports, test cases, and code contributions are [more than 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/russross/blackfriday](https://github.com/russross/blackfriday) | Russ Ross | Markdown processing | Simplified BSD License |
| [github.com/sass/libsass](https://github.com/sass/libsass) | Listed [here](https://https://github.com/sass/libsass) | C port of the Ruby SASS compiler | MIT License |
| [github.com/tdewolff/minify](https://github.com/tdewolff/minify) | Taco de Wolff | CSS minimization | MIT License |
| [github.com/wellington/go-libsass](https://github.com/wellington/go-libsass) | Drew Wells | Go bindings for **libsass** | ??? |
| [gopkg.in/alecthomas/kingpin.v2](https://github.com/alecthomas/kingpin) | Alec Thomas | command-line arguments | 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 (+++).
[jkl](https://github.com/drone/jkl) is another Go clone of Jekyll. If I'd found it sooner I might have started this project by forking that one. It's got a better name.
[Liquid](https://github.com/osteele/liquid) is a pure Go implementation of Liquid templates, that I finally caved and wrote 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-report-card-url]: https://goreportcard.com/report/github.com/osteele/gojekyll
[go-report-card-svg]: https://goreportcard.com/badge/github.com/osteele/gojekyll
[travis-url]: https://travis-ci.org/osteele/gojekyll
[travis-svg]: https://img.shields.io/travis/osteele/gojekyll.svg?branch=master
Reference in New Issue View Git Blame Copy Permalink