ssg-blog

This is a modification to the simple static site generator ‘ssg’ by Roman Zolotarev. This is a markdown to HTML static site generator that also creates a minimal blog index page with category headings and posts sorted by date using YAML frontmatter in markdown files.

It also generates a sitemap.xml and rss.xml file.

demo of generated site

Install / Usage

See https://romansolotarev.com/ssg.html for documentation on ssg. Install lowdown and cpio.

git clone https://git.historia.vg/git/ssg-blog
cp ssg-blog/ssg-blog /usr/bin/                  # (or somewhere in your path)
chmod +x /usr/bin/ssg-blog
ssg-blog src dst 'https://my-website.net'

ssg-blog checks for subdirectories in the src directory, each of which becomes a category heading (non-recursively). It will generate a sorted list of links to any .md file in those directory (including nested directories).

ssg-blog/
├─ src/
│  ├─ category/
│  │  ├─ article1_dir/
│  │  │  ├─ article1.md
│  │  │  ├─ some_assets/
│  │  │  │  ├─ some_header.png
│  │  ├─ article2.md
│  │  ├─ article3.md
│  ├─ another_category/
...

Each .md file may include frontmatter with the title and a YYYY-MM-DD date like this to be included in the index page:

---
title: My Blog Post
date: 2024-10-09
publish: false
---

If a file has no frontmatter, no date, or publish: false, the page won’t be included in the index, sitemap, or RSS feed.

Setting publish: true is optional and equivalent to not having publish at all.

Demo

There is a demo directory in this repo to show you an example of how to set up the files (src) and what the output looks like (dst). This was the command used to generate the demo output:

./ssg-blog demo/src demo/dst 'https://example.org'

Note a few things about the output: 1. Markdown files can be nested in subdirectories or not. 2. Files named index.md will get have a link generated without .html at the end. 3. Files outside subdirectories (e.g. about.md) will be rendered but won’t show up on the index.

Change how categories are sorted

The category headings are sorted alphabetically. If you want to change this, you have to edit the sort on this line:

find "$src" -mindepth 1 -maxdepth 1 -type d ! -path "*/.*" | sort |

Differences from ssg

The title argument from ssg is unnecessary so I’ve removed it. render_html_file used it to modify the first <h1> tag and auto-populate the <title> if none is specified, which is functionality I’ve never needed. Instead I check the frontmatter of each blog post and update the <title> tag with the title: field.

Alternatives

You might also be interested in the similar fork fmash16/ssg5 which generates a more traditional blog with pagination, keywords, and post previews.