Designing a Python Static Site Generator for Markdown-to-HTML Conversion

Abstract

Tämä opinnäytetyö dokumentoi Python-pohjaisen staattisen sivustogeneraattorin, joka muuntaa Markdown-sisällön HTML-muotoon käyttäen pelkästään Pythonin standardikirjastoa. Järjestelmä käyttää kaksivaiheista jäsentämisstrategiaa (lohkot, sitten sisäiset elementit) ja mallipohjapohjaista renderöintiä. Toteutus painottaa selkeyttä ja opetuksellista arvoa. Työ sisältää yksikkötestit ja analysoi suunnitteluvalintoja, rajoituksia sekä mahdollisia laajennuksia.

This thesis documents and evaluates a Python-based static site generator that converts Markdown content into HTML through a transparent, template-driven pipeline. The implementation relies solely on the Python standard library and emphasizes clarity and educational value over feature breadth. The system performs a deterministic build: it cleans and copies static assets, discovers Markdown files under a content directory, parses them with a two-phase approach (block classification followed by inline processing), composes HTML via lightweight node abstractions, injects the result into a template, and rewrites root-relative paths for subdirectory hosting. The work analyzes design choices, correctness, and maintainability using focused unit tests that cover node rendering, block/inline parsing, title extraction, and basic HTML generation. Results show that a compact codebase can produce predictable, standards-aligned output suitable for small sites and learning purposes. The thesis also identifies limitations (partial CommonMark coverage, minimal templating, string-based path rewrites) and outlines practical extensions, including richer inline features, front matter, and improved HTML rendering details.