I have a small pile of side projects, and one of them is staticgen: a static site generator in Python with no dependencies at all. The goal was not to replace Hugo. The goal was to understand it.
The first version is 37 lines. It reads a folder of markdown, turns it into HTML, and drops it into a template:
def render(post_md, template): lines = post_md.strip().split("\n") out = [] for line in lines: if line.startswith("# "): out.append("<h1>" + line[2:] + "</h1>") elif line.startswith("## "): out.append("<h2>" + line[3:] + "</h2>") else: line = line.replace("**", "<strong>", 1).replace("**", "</strong>", 1) out.append("<p>" + line + "</p>") body = "\n".join(out) title = lines[0].lstrip("# ").strip() return template.replace(TITLE, title).replace(BODY, body) It worked on the one test post I wrote. Then I fed it something realistic, and it fell apart in four ways worth knowing about.
1. The bold replacement eats exactly one pair
That .replace("**", ..., 1) chain is a neat trick that breaks the moment a line has two bold runs. Actual output from the code above, on Some **bold** and **more bold** here.:
<p>Some <strong>bold</strong> and **more bold** here.</p> The first ** became <strong>, the second became </strong>, and the remaining four asterisks were left alone. Any line with more than one bold span renders literally.
The fix is not a better loop over replace. It is one regex pass that consumes both cases:
BOLD = re.compile(r"\*\*(.+?)\*\*") line = BOLD.sub(r"<strong>\1</strong>", line) .+? is lazy, so it matches the shortest run between two delimiters. That handles one pair or ten, and it fails visibly instead of silently leaving artifacts.
2. Nothing is escaped
This line went straight through:
<p>a < b && c > d</p> A naked < makes browsers guess, and the guess is not always what you want. Escape first, then add markup:
import html line = html.escape(line, quote=False) Do it before the bold pass, otherwise you escape your own tags. Order matters here, and it stays hidden until a post mentions generics or a comparison operator.
3. Every blank line becomes an empty paragraph
<p></p> <p>Some <strong>bold</strong> here.</p> <p></p> Harmless-looking, annoying in practice: it adds gaps you cannot style away without an :empty rule, and it bloats the HTML of ordinary prose. Skip blank lines and let them separate paragraphs instead:
if not line.strip(): continue 4. Fenced code blocks get mangled, which is the real bug
A fenced block came out as three paragraphs, and markdown inside the code was interpreted. The fence markers ended up wrapped in <p> tags, and **not bold** was bolded inside what should have been literal code.
For a developer blog this is fatal. Code samples are the content. A line-by-line renderer with no state cannot handle it, so the renderer needs a mode switch:
in_code = False for line in lines: if line.startswith("```"): out.append("<pre><code>" if not in_code else "</code></pre>") in_code = not in_code continue if in_code: out.append(html.escape(line)) continue ... That is the whole lesson of the project, and it is the same lesson every time I have written a small parser: the naive version is not wrong about the concept, it is wrong about state. Bold spans, fences, lists, and escaping all need to know what came before.
Where it stands
staticgen is now about 90 lines, still dependency-free, and it builds my posts without surprises. It has a --template flag and a sample post in posts/. It is not a Hugo competitor: no incremental builds, no taxonomies, no front matter beyond a leading # heading.
What it gave me was cheap. Two hours, and now I know exactly why the markdown pipeline in every tool I use is more complicated than it looks.
If you want the same exercise, pick the smallest tool you rely on and rewrite the dumb version of it. The bugs will teach you more than the docs.
