Giter Club home page Giter Club logo

gojekyll's Introduction

Gojekyll

All Contributors

go badge Golangci-lint badge Coveralls badge Go Report Card badge MIT License

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

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

  1. Linux, Mac OS and Windows binaries for x86, amd64, armv6/v7, armv8, riscv64 are available from the releases page.
  2. Download the latest version of dart-sass and add it to your PATH, or see the Sass website for full installation instructions.
  3. [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:

  1. Install go (1) via Homebrew: brew install go; or (2) download.
  2. 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:

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
    • 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

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

gojekyll's People

Contributors

bep avatar chimbori avatar danog avatar mevdschee avatar osteele avatar sirwart avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

gojekyll's Issues

Implement `--incremental`

The flag should be implemented for compatibility with Jekyll, but should do nothing. For now at least, emphasize making whole builds fast enough that it's not needed.

New pygmentize detection breaks in go < 1.16

(As referenced here:) tags/highlight.go won't compile in go < 1.16, because it uses "io/fs":

build github.com/osteele/gojekyll: cannot load io/fs: malformed module path "io/fs": missing dot in first path element

Previous versions used this code to test for the absence of the pygmentize command, but it does not work in go 1.16 because the error is not on the specified type:

	if e.Err == exec.ErrNotFound {

831ea53 changed to use this code, but this code does not compile in go < 1.16:

	if pathErr, ok := err.(*fs.PathError); ok {

Add a plugin hook for post-HTML conversion

Some plugins (e.g. jekyll-mentions) need to operate on text inside of HTML.

Add an HTML parsing staging after Liquid and Markdown conversion, and a plugin hook for this.

Does parsing the HTML affect performance? If so, only do if one of the plugins has used this hook.

`serve` should build all the pages

The server builds all the collections, but only generates non-collection pages on demand. It should build everything, so that it can report all the errors.

Websocket error when navigate to non-root URL

Checklist

  • I have search the issue list for my issue.
  • I have verified the behavior with jekyll.
  • I tried hard to create a reproducible test case.

System information

Liquid version: gojekyll --version
develop
Commit hash: (if version = develop)
9718b42

Expected behavior

Hyperlinks and all URLs work correctly.

Actual behavior and reproducer

Only the index page loads. All other pages (which are linked from the index page) give 404. I get the following error in gojekyll serve console output when I navigate to some other page (for example, clicking on the "articles" hyperlink on the home page).

# I run "gojekyll serve", server is running
Configuration file: /home/apb/code/abhijeetbodas2001.github.io/_config.yml
            Source: /home/apb/code/abhijeetbodas2001.github.io
    Server address: http://127.0.0.1:4000/
  Server running... press ctrl-c to stop.
# I now open my browser, and click on the "articles" hyperlink on the homepage (which goes to the localhost:4000/articles URL)
# I now get a 404 (I have a custom 404 page, which shows up in the browser.
# The following error pops up in console output:
[LiveReload] websocket: close 1001 (going away)
[LiveReload] websocket: close 1001 (going away)

I have my site source at https://github.com/abhijeetbodas2001/abhijeetbodas2001.github.io and am currently trying out gojekyll (have used only the ruby gem earlier).
I am running Debian 12 bookworm.

Would appreciate any sort of help on how to fix this. Thanks for all your efforts on this project!

gojekyll build overwrites a _site symlink with a directory

System information

Fedora 38 x86_64

Liquid version: gojekyll --version
gojekyll version 2c83a35 (Build time: 2023-08-18T20:44)

Expected behavior

gojekyll to follow the symlink

Actual behavior

gojekyll overwrites the symlink with a directory

Steps to reproduce the behavior

  1. cd example
  2. rm -rf _site
  3. mkdir ~/blog
  4. ln -s ~/blog _site
  5. gojekyll build

`jekyll-redirect-from`

Implementation plan:

  1. site build asks config whether the plugin is active. If so, it iterates over each page's front matter's redirect_from list

  2. page load asks config whether the plugin is active. If it is and if the front matter contains a redirect_to, it changes this to a permalink and creates or appends the original page permalink to a redirect_from, so that downstream processing will do the right thing.

Themes

Implementation plan:

  • Site.Read adds the files in $theme/assets, before adding the files in the main site (so that the latter takes precedence)
  • layouts looks in $themes/_include, after looking in the main _include
  • include_relative from the theme directory needs to look first in the corresponding non-theme location
  • The sass copier should first copy files from $themes/_sass, then overwrite them with $site/_sass

Emulate the `jekyll-readme-index` plugin

Implementation plan:

Site.Read asks the config whether this plugin is present. If it is, it changes the permalink of any document with README.htmlto / before putting it in the routing table.

Extensionless serving is not supported: `/page` returns 404 when `/page.html` returns 200

Checklist

  • I have search the issue list for my issue.
  • I have verified the behavior with jekyll.
  • I tried hard to create a reproducible test case.

System information

Liquid version: gojekyll --version

Commit hash: v0.2.8 (built from source)

Expected behavior

Jekyll serves any page without the .html extension correctly, both during development and on GitHub Pages.

Actual behavior

GoJekyll returns a 404 for /page, but 200 for /page.html

Steps to reproduce the behavior

Provide the first of these that is practical:

Trivial enough that I did not create a minimal test case, but let me know if you cannot proceed without one.

Possible Solution

Support extensionless serving; let me know if this is something you’d like to support, and I can take a stab at implementing it & send you a PR.

when running go install gojekyll get error

Checklist

  • I have search the issue list for my issue.
  • [x ] I have verified the behavior with jekyll. (N/A)
  • I tried hard to create a reproducible test case.

System information

Rocky 8
(installing error)

Expected behavior

go install github.com/osteele/gojekyll@latest will install & put a binary

Actual behavior

doesn't install, fails with the following:

...
go: github.com/osteele/gojekyll imports
	github.com/osteele/gojekyll/commands imports
	gopkg.in/alecthomas/kingpin.v2: gopkg.in/alecthomas/[email protected]: parsing go.mod:
	module declares its path as: github.com/alecthomas/kingpin/v2
	        but was required as: gopkg.in/alecthomas/kingpin.v2

Steps to reproduce the behavior

Rocky 8,
Go 1.19.1
go install l github.com/osteele/gojekyll@latest

Possible Solution

Fix go.mod file

Use goreleaser to build releases

Expected behavior

Add a draft release to project releases https://github.com/osteele/gojekyll/releases.

Actual behavior

❯ goreleaser --rm-dist
   • running goreleaser dev   
   • loading config file       file=.goreleaser.yml
   • SETTING DEFAULTS 
   • GETTING AND VALIDATING GIT STATE
   • LOADING ENVIRONMENT VARIABLES
   • CHECKING ./DIST  
   • rm-dist is set, removing ./dist
   • BUILDING BINARIES
   • skipped ignored build     target=darwin/386
   • new folder                folder=gojekyll_0.0.1_macOS_64bit key=darwinamd64
   • building                  binary=dist/gojekyll_0.0.1_macOS_64bit/gojekyll
   • new folder                folder=gojekyll_0.0.1_Linux_64bit key=linuxamd64
   • building                  binary=dist/gojekyll_0.0.1_Linux_64bit/gojekyll
   • new folder                folder=gojekyll_0.0.1_Linux_32bit key=linux386
   • building                  binary=dist/gojekyll_0.0.1_Linux_32bit/gojekyll
   ⨯ release failed            error=build failed for linux/386:
go build github.com/jeffjen/datefmt: no buildable Go source files in /Users/osteele/go/src/github.com/jeffjen/datefmt
# github.com/wellington/go-libsass/libs
../../wellington/go-libsass/libs/sass_number.go:8: undefined: SassNumber
../../wellington/go-libsass/libs/sass_number.go:151: undefined: SassNumber
../../wellington/go-libsass/libs/sass_number.go:153: undefined: SassNumber
../../wellington/go-libsass/libs/sass_number.go:157: undefined: SassNumber
../../wellington/go-libsass/libs/sass_number.go:159: undefined: SassNumber
../../wellington/go-libsass/libs/sass_number.go:164: undefined: SassNumber
../../wellington/go-libsass/libs/sass_number.go:166: undefined: SassNumber
../../wellington/go-libsass/libs/sass_number.go:170: undefined: SassNumber
../../wellington/go-libsass/libs/sass_number.go:175: undefined: SassNumber
../../wellington/go-libsass/libs/sass_number.go:186: undefined: SassNumber
../../wellington/go-libsass/libs/sass_number.go:166: too many errors

Steps to reproduce the behavior

❯ go get github.com/goreleaser/goreleaser
❯ git tag -af v0.0.1 -m "First release" && git push origin +v0.0.1
❯ goreleaser --rm-dist

More info

There appear to be two distinct problems: the "no buildable Go source files" warning re github.com/jeffjen/datefmt; and the "undefined: SassNumber" errors re github.com/wellington/go-libsass.

Before I added main: ./cmd/gojekyll to .goreleaser.yml, the commands above did create a release. The gojekyll in the release zip wasn't executable, though, since the config didn't refer to a main package. The build probably was skipping all the compilation, which is why it didn't run into the errors above. This does demonstrate that the upload part is (was) working.

`build` and `serve` terminate when encountering the first file that cannot be parsed

Checklist

  • I have searched the issue list for my issue.
  • I have verified the behavior with jekyll.
  • I tried hard to create a reproducible test case.

System information

Liquid version: 9718b42

Steps to reproduce the behavior

Minimal test case:

<div markdown="1">

<br>
<br>

</div>

Actual behavior

  1. When a single file cannot be parsed, gojekyll terminates. With the current behavior, you have to fix one file at a time, and cannot see any patterns that might have been otherwise obvious.
  2. gojekyll terminates with filename.md: markdown: EOF. This is not enough information to debug what’s wrong in that file.
  3. The file contains markdown="1". Although the README says markdown="span" and markdown="block" are not supported, it does not explicitly say that markdown="1" is not supported.

Expected behavior

  1. Keep going even if one file has an error, and report all errors to the user.
  2. A better error message than filename.md: markdown: EOF would really help in debugging, especially if a feature is known not to be supported.
  3. If the lack of support for markdown="1" is a known issue, then this should be added to the README in addition to markdown="span" and "block".

Possible Solutions

Listed above.

Thanks for a great tool, hoping I can use it as a drop-in replacement soon!

Allow `collections` to be a list instead of a map

Implementation plan:

  • Add a struct collectionList {collections []string} type.
  • Reading config.yml unmarshals into this. If it's not empty, it creates a map and assigns the configuration from it.

The configuration struct currently specifies a map. Does this cause an error if the YAML is a list?

If so:

  • mark Config.collections with yaml:"-"
  • define collectionMap struct
  • unmarshal into collectionMap
  • assign Config.collections from collectionMap.collections

jekyll-github-metadata should cache data

The jekyll-github-metadata plugin should have an option to cache GitHub requests. This would make it easier to run benchmarks that (1) don't include network latency (which is large over slow network connections, and highly variable in general).

Vendor dependencies

This should happen as the project becomes more stable. I don't know if it's worth it yet.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.