6 releases
0.0.6 | Feb 1, 2023 |
---|---|
0.0.5 | Jan 20, 2023 |
0.0.2 | Feb 6, 2022 |
#205 in Command line utilities
37KB
680 lines
⚠️ 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 withbuild --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.
Dependencies
~11–18MB
~350K SLoC