Static Site Generator
Overview
This is a small static site generator I built from scratch in Python as a guided learning project. It converts Markdown files into HTML, applies a shared template, copies static assets, and recursively generates the finished website.
The goal was to understand how a static site generator works internally by implementing the basic pipeline myself.
Why I Wanted to Build This
Before starting the project, I did not know about static site generators by name or tools such as Hugo and Jekyll. I only knew that writing HTML pages by hand could become tedious. While working through the guided project, I learned how static site generators avoid repeating the same HTML structure and how their internal steps fit together.
Building this was a lot of fun and gave me hands-on practice with Markdown parsing, HTML nodes, recursion, file processing, and tests.
What did I want to understand?
- 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.