SSG Build Tool Comparison

Tags: code

A concrete Bash-only implementation that stays within your original structure using:

Makefile to control dependencies
Bash scripts to:
- Convert .md to .html with Pandoc
- Generate index.html listing all posts by date
- Generate tag pages

Task	Bash	Python	Comment
Running Pandoc	✅	✅	Both fine
Parsing YAML	⚠️ Fragile	✅ Robust	Python is safer
Sorting posts by date	❌ Hard	✅ Easy	Use Python
Template rendering	❌ No support	✅ jinja2 etc.	Use Python
Managing dependencies	✅ with Make	✅ with Make	Either
Portability/minimalism	✅ Bash wins	❌ Needs Python	Bash wins
Maintainability	❌ Declines fast	✅ Cleaner	Python wins

project/
├── content/
├── layout/
├── pages/
├── scripts/
│   ├── build_index.sh
│   └── build_tags.sh
├── Makefile

Specifications for a static site generator using:

Makefile for automation
Bash for scripting tasks
Pandoc for converting Markdown to HTML
Markdown files (e.g., 2022-07-15-xyz.md) as content sources

Sample markdown file:

---
title: About
date: 2025-02-02
tags: 
  - about
  - music
description: Continuum is a simple notes repository where I irregularly post my notes.
---

Continuum is a personal repository where I occasionally post my notes, starting from May 15, 2023. However older notes, written before that date, are also archived.

I primarily write by hand as a means of processing my thoughts and enhancing my comprehension. These notes serve as a valuable reference for both the present and the future, and the daily practice of writing them has become a personal memory tool, especially as I age.

Directory Structure

CONTENT_DIR = "content"
OUTPUT_DIR = "pages"
TEMPLATE = "layout/default.html"
TAG_TEMPLATE = "layout/tag.html"

Features

Support for tags, citations, and LaTeX math

Use of Pandoc with the following options:

pandoc --standalone -f markdown \
        --lua-filter=dropcap.lua \
        --lua-filter=mdlinks.lua \
        --lua-filter=mermaid.lua \
        --template="$TEMPLATE" \
        --mathjax \
        --bibliography=./refs.json \
        --citeproc \
        --csl=./apa.csl

Output

index.html should list all content HTML files in chronological order (like a blog), grouped by year, current year expanded, older ones collapsed
Include a tag cloud for easy navigation
Each post supports tags, citations, and math rendering

Desired Behavior

Only rebuild pages/foo.html if content/foo.md has changed
Only rebuild index.html if any .html post file changed or was newly added/removed
Only rebuild tag pages if:
- Any .md file’s tags changed
- A .md file was added or removed
- Or a tag page doesn’t exist yet