Static Site Generator
Overview
This is a small static site generator I built from scratch in Python. It is inspired by tools like Hugo and Jekyll, but much simpler: it takes Markdown files, combines them with a shared HTML template, copies static assets, and writes out a finished static website.
The goal was not to replace mature tools. The goal was to understand what happens underneath them by building the basic pipeline myself.
Why I Built This
I started looking into static site generators because expanding this website by writing HTML by hand can become tedious. At first, I did not even know the term "static site generator"; I just wanted a faster way to turn content into pages without repeating the same HTML structure over and over.
Why build my own instead of just using Hugo?
- Learning: I wanted to understand the moving parts instead of only using the finished tool.
- Python practice: It was a good way to work with file handling, recursion, and parsing.
- Project structure: It forced me to separate content, templates, static assets, and generated output.
How It Works
The project follows a simple content pipeline:
-
content/: -
template.html: -
static/: -
docs/:
The generator walks the content directory recursively, converts Markdown blocks into HTML nodes, injects them into the template, and writes one HTML file for each Markdown page.
Why It Does Not Power This Website
This portfolio is still small, custom-built, and updated infrequently. Writing these pages by hand gives me more control over layout and navigation, especially for pages like the Homelab section where each page needs slightly different structure and links.
My generator currently supports one shared template for all pages. That is useful for a simple demo site, but too limited for the more handcrafted parts of this website.
Lessons Learned
- Recursive file generation becomes much easier once content and output paths are modeled clearly.
- A shared template is powerful, but real websites quickly need layout flexibility.
- Deployment paths matter; a GitHub Pages project page needs the correct base path for CSS and images.
Demo
The demo site is a small generated article. It uses a Revenge of the Sith essay as sample content so the generator has headings, paragraphs, images, links, and blockquotes to render.