# ssg-blog

This is a modification to the simple static site generator '[ssg](https://romanzolotarev.com/bin/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](demo/demo.webp)

# Install / Usage

See [https://romansolotarev.com/ssg.html](https://romanzolotarev.com/ssg.html) for documentation on ssg. Install [lowdown](https://kristaps.bsd.lv/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'
```

Blog categories are hard-coded in the `CATEGORIES` variable at the top of the script. Each one becomes a category heading in the order listed. Blog posts should be in a directory with the same name.

```
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:

```markdown
---
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 <filename>.html at the end.
3. Files outside subdirectories (e.g. about.md) will be rendered but won't show up on the index.

# 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](https://github.com/fmash16/ssg5) which generates a more traditional blog with pagination, keywords, and post previews.