Tags: code bash python ssg

A minimal, extensible static site generator using make, pandoc, and shell scripts. It converts Markdown files into styled HTML, supports tags, search indexing, RSS feeds, and versioning.

Features

• Converts Markdown (.md) to standalone HTML using pandoc
• Custom HTML templates and Lua filters
• Auto-injected tag links
• Per-tag HTML pages
• Bibliography and citations (refs.json + apa.csl)
• RSS feed generation
• Search indexing using search_generator.py
• Timestamped version snapshots
• Local development server

Requirements

• make
• pandoc
• python3
• awk, bash, and common Unix tools
• Pandoc Lua filters (e.g., dropcap.lua, mdlinks.lua, etc.)

Directory Structure

.
├── content/               
│   └── *.md               # Source Markdown posts (excluding index.md)
├── pages/                 
│   └── *.html             # Generated HTML files
├── layout/
│   ├── default.html       # Main page template
│   ├── tag.html           # Tag page template
│   └── style.css          # Site stylesheet
├── scripts/
│   ├── build-index.sh
│   ├── build-rss.sh
│   ├── build-single-post.sh
│   ├── build-tag-pages.sh
│   ├── dropcap.lua
│   ├── mdlinks.lua
│   ├── mermaid.lua
│   └── search_generator.py
├── tag_temp/              # Temporary files for tag generation
├── refs.json              # Optional bibliography file
├── apa.csl                # Optional CSL file for citation formatting
├── Makefile               # Build automation with GNU Make
└── README.md              # Project documentation

Setup

1. Create a Python virtual environment. make venv
2. Run pip install beautifulsoup4
3. Build the entire site make
4. Serve locally make serve
5. Cleanup make clean       # Removes generated HTML, CSS, and tag data
6. Rebuilding make rebuild # Clean and rebuild everything from scratch
7. Versioning make version

Available Make Targets