stoic

is a simple static blog generator created to learn about Rust and its library ecosystem.

Installation

cargo install stoic

Usage

stoic new blog

generates a new blog in the blog/ directory with file structure:

blog
├── about.md
├── index.md
├── assets
│   ├── script.js
│   └── style.css
├── posts
│   └── 2022-01-26-hello-world.md
└── templates
    ├── base.hbs
    ├── index.hbs
    ├── nav.hbs
    ├── page.hbs
    ├── post.hbs
    └── posts.hbs

You can run:

stoic build blog dist

to have stoic generate the corresponding static html in the dist/ directory with file structure:

dist/
├── about.html
├── index.html
├── assets
│   ├── script.js
│   └── style.css
└── posts
    ├── 2022-01-26-hello-world.html
    └── index.html

stoic watch blog dist

tells stoic to watch the blog/ for changes and rebuild the blog automatically.

It will run a static web server @ 0.0.0.0:3030. After each rebuild your browser should automatically reload.

Collections

The site created by the new command above contains a single collection: posts. The collection is identified by the name of the folder. All markdown files in this folder are treated as items of this collection. In the templates folder are the posts.hbs and post.hbs templates. The posts.hbs template is used when generating the index of the collection. The post.hbs template is used when generating each item in the collection.

To create a new collection i.e. works:

1. create folder works
2. create templates/works.hbs template
3. create templates/work.hbs template
4. put work markdown files in the works folder

Collection Item Metadata

Markdown items in collection folders should contain a metadata section at the top of the file:

<!--metadata
date = 2023-03-25
shortname = "Foo Bar"
slug = "foo_bar
-->

date is a date in the YYYY-MM-DD format. The date should exist in all collection items as it is used for sorting.

shorname is the label used for the entity in the breadcrumbs. If it is not provided then the date will be used.

slug is a name for the output file. If you have an input file foo.md but want the output file to be foo_bar.html instead of the default foo.html, set the slug to foo_bar.

Examples

• unsafe-perform.io - repo