⚠️ This project is a work in progress, very little of what is described below works as of now.

Kobold

Kobold is a static site generator with a friendly CLI.

Installation

You can install Kobold via cargo as long as you separately provide its assets:

$ cargo install kobold-ssg
$ KOBOLD_VERSION=v$(kobold --version | cut -d' ' -f2)
$ # download assets
$ curl 'https://gitlab.com/eguiraud/kobold-ssg/-/archive/${KOBOLD_VERSION}/kobold-ssg-${KOBOLD_VERSION}.tar.gz?path=assets' | tar -xzv
$ # tell kobold where to find them
$ export KOBOLD_ASSET_DIR='kobold-ssg-${KOBOLD_VERSION}-assets/assets'
$ # can now use kobold as usual
$ kobold init example.com

Alternatively you can clone this repository and cargo run it.

Quick start

Create a new Kobold project:

$ kobold init hello_kobold/

This creates the hello_kobold/ directory and initializes it as a git repository with the directory structure that Kobold requires:

hello_kobold/
├── content/
│   └── index.md
├── page_layouts/
│   └── default.html
├── snippets/
│   └── ...
└── css/
    └── ...

All sub-directories except content/ can be empty or can be omitted from your project. The project can contain sub-directories with other names, but sub-directories site/ and site.old/ are reserved for usage by Kobold.

If you have used any other static site generator, you can probably guess how Kobold works based on this directory structure.

The index.md file is the main page of the website, and starts with the following contents:

---
title: Home page
---

# Hello kobold!

You can already generate the output website:

$ kobold build hello_kobold/

That command creates a site/ sub-directory in the hello_kobold/ directory with the generated website. You can visit the website with your favourite web browser:

$ firefox hello_kobold/site/index.html

You can then work on your website by adding more files under content/: files with .md extension are processed to transform Markdown into HTML and to apply the desired page layout (by default, default.html), all other files and directories are copied into site/ as they are. The page layout can be customized by modifying page_layouts/default.html or by adding other page layouts and specifying they should be used by adding layout: yourlayout.html to the Markdown's front matter: just add a {{ body }} template in the layout that will be substituted with the actual page content during the website build.

Notable features

• human-friendly error messages that are prescriptive rather than descriptive whenever possible
• nice autocompletion for the fish shell is available
• automatic generation of a /tags page that categorizes website contents by tag (turn it off with build --no-tags)
• built-in integration with Stork to generate a search bar for the website (build --with-search-bar option)
• Kobold tries hard to make generated websites completely relocatable, which has two advantages
  • the generated website can be copied as-is and it will usually be served correctly independently of the path it is served from
  • to preview the generated website, it is sufficient to open any of its HTML files in a browser; no webserver is needed

Why?

I wanted a personal website and I wanted to practice my Rust.

Related work

Kobold was written from scratch, but it has many similarities to the more mature Zola and Cobalt. Kobold lacks many of their features, but in exchange it tries to be so easy to use that you basically can start working on your website without reading any docs, just playing with the kobold command.

I also appreciate Hugo's focus on speed and its no-nonsense workflow, and shortcodes make a lot of sense so Kobold's templates try to replicate some of that usefulness.

Not a static site generator per se, but a honorable mention goes to Sylvain Kerkour's Building a static site generator in 100 lines of Rust which was a great resource to get me started.

Contributing

Contributions in the form of issues and pull requests are welcome.