Kobold

Kobold is a static site generator with a friendly CLI.

Installation

You can install Kobold via Cargo:

```bash cargo install kobold-ssg

as long as cargo's bin directory is in your PATH, you are set

kobold -h A static site generator with a friendly CLI

Usage: kobold

Commands: init Create a new Kobold project in the specified directory build Generate website from the Kobold project at the specified directory help Print this message or the help of the given subcommand(s)

Options: -h, --help Print help -V, --version Print version ```

Alternatively you can clone the repository: executing cargo run within it runs the kobold executable.

Quick start

Create a new Kobold project:

bash kobold init koboldsite.com

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

koboldsite.com/ ├── content/ │   └── index.md ├── page_layouts/ │ └── default.html ├── macros/ │ └── ... └── 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:

```yaml

title: Home page

Hello Kobold!

```

You can already generate the output website:

bash kobold build koboldsite.com

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

bash firefox koboldsite.com/site/index.html

You can then work on your website by adding more files under content/. Files with the .md extension are processed to transform Markdown into HTML and to apply the desired page layout (by default, default.html). All other files are copied into site/ as they are, with the same directory structure.

The page can be customized by modifying page_layouts/default.html. Custom page layouts can be added to the page_layouts directory: they are Tera templates (similar to Jinja2 templates), i.e. HTML files with placeholders such as {{title}} and {{body}}. These placeholders will be replaced by each page's title and HTML content during the Kobold build.

To select a custom page layout add layout: filename.html to the page's YAML frontmatter.

Roadmap

• [X] human-friendly error messages that are prescriptive rather than descriptive whenever possible
• [ ] support for programmatic generation of page content via Tera macros
• [ ] automatic generation of a /tags page that categorizes website contents by tag
• [ ] nice autocompletion for the fish shell is available
• [ ] automatic generation of a search bar using Stork

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

If you happen to try out Kobold, any feedback is more than welcome.

Contributions in the form of issues or patches are even more appreciated.