⚠️ 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 (substitute the desired version instead of v0.0.4 below):

$ cargo install kobold-ssg $ KOBOLD_VERSION=v$(kobold --version | cut -d' ' -f2) $ curl 'https://gitlab.com/eguiraud/kobold-ssg/-/archive/${KOBOLD_VERSION}/kobold-ssg-${KOBOLD_VERSION}.tar.gz?path=assets' | tar -xzv $ export KOBOLD_ASSET_DIR='kobold-ssg-${KOBOLD_VERSION}-assets/assets'

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

layout: default

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

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.