cd /news/structured-data/markdown-to-html-0-llm-tokens-for-4-… · home › topics › structured-data › article
[ARTICLE · art-173540] src=dev.to ↗ pub= topic=structured-data verified=true sentiment=↑ positive

Markdown to HTML: 0 LLM Tokens for 4 Posts, 23 FAQs Extracted

A developer built a deterministic Markdown-to-HTML converter that published four manuscripts (43,699 bytes) using zero LLM tokens, automatically extracting 23 FAQ questions while all four posts passed built-in self-checks. The converter exits with code 1 on spec violations and reports faq_count and html_len to catch formatting drift, stripping the H1 from the body and pulling FAQ entries only from the FAQ section to avoid structured-data mismatches. The developer argues scripts should handle fixed-format conversion where output must be byte-for-byte reproducible, reserving LLMs for work that requires judgment.

recommendation

Route fixed-format conversion to a script that exits non-zero on spec violations and reports faq_count and html_len, reserving LLM calls for tasks that need judgment.

more in playbook: Controlling LLM cost
by read6 min views5 publishedNov 20, 2026

We needed to publish four manuscripts (43,699 bytes in total) that another project had handed over, and the obvious move was to ask an LLM to turn the markdown into HTML. We wrote a deterministic converter instead. It used zero LLM tokens, extracted 23 FAQ questions automatically, and all four posts passed its built-in checks. The reason is not cost. The manuscripts already contained values that had been cross-checked by hand, such as notice numbers and page numbers, so changing a single character during formatting would itself be a defect.

This post covers the rule we use to decide between a script and an LLM, what the converter actually does, and the two publishing traps it closed without anyone having to remember them.

Ask these about the step you are about to automate. A single "yes" means use a script.

Question If yes If no
Must the same input always give the same output? Script LLM is fine
Must source values stay byte-for-byte unchanged? Script LLM is fine
Can pass or fail be decided automatically from an exit code? Script LLM is fine

Our conversion answered yes to all three. The manuscripts already followed a fixed layout (title, three-line summary, tables, a Q/A list), the rules for turning that layout into tags were unambiguous, and compliance could be checked with plain string searches. Work that needs judgment, such as summarizing, restructuring, or adjusting tone, belongs to the LLM. Moving a fixed format into fixed tags does not. The short version: if judgment is needed, use an LLM; if there is a rule, use a script.

There is a cost argument too, but it is the weakest of the three. A few posts are cheap either way, yet an LLM step also gives you a different output on each run and a chance to quietly touch a number. Those two problems are what actually hurt.

The script takes one markdown file and produces body HTML plus a metadata JSON. If it finds a spec violation it exits with code 1.

python -X utf8 scripts/publish/md2bsp.py post.md out/body.html --meta out/meta.json

Standard output is two lines. The first is the metadata, the second is the self-check result:

{"title": "<from the H1>", "excerpt": "<first item of the 3-line summary>", "faq_count": <n>, "html_len": <n>, "src": "post.md"}
self-check: PASS

(The full manuscript and converter output checklists are in the original post.) Two numbers catch most formatting accidents. If faq_count differs from what you expect, the Q/A format in the manuscript drifted. If html_len is far smaller than the source, part of the body was not parsed.

The converter also removes the H1 from the body and uses the first summary item as the excerpt. Our platform renders the title separately, so leaving the H1 in the body would show it twice.

FAQ entries are pulled only from the FAQ section of the body. That keeps the structured data from containing questions the page never shows, which search engines flag as a mismatch. A runnable version of the idea looks like this:

import re

def extract_faq(md):
    m = re.search(r"\n##\s*FAQ\s*\n(.*?)(?=\n##\s|\Z)", md, re.S)
    if not m:
        return []
    return re.findall(
        r"\*\*Q\.\s*(.+?)\*\*\s*\n\s*A\.\s*(.+?)(?=\n\s*\n|\Z)",
        m.group(1), re.S,
    )

sample = "\n## FAQ\n**Q. Why a script?**\nA. Same input, same output.\n\n** Q. Cost?**\nA. Zero tokens.\n"
print(len(extract_faq(sample)))  # 2

The regular expression enforces the format. If the section heading differs, the question line is styled differently, or an answer does not begin with A., that pair is simply not captured. In other words, the manuscript format becomes the parser's input specification. On these four posts the approach extracted 23 questions with no manual step.

The last block of the converter counts the things that must not ship: a leftover style block, a leftover h1 tag, a leftover TODO marker, a leftover emoji, or a missing title. Any hit makes the process exit with 1.

import re

def check(html, title):
    bad = []
    if "<style" in html:
        bad.append("style block left")
    if "<h1" in html:
        bad.append("h1 left")
    if "TODO" in html:
        bad.append("TODO left")
    if re.search("[\U0001F300-\U0001FAFF]", html):
        bad.append("emoji left")
    if not title:
        bad.append("no H1 title")
    print("self-check:", "PASS" if not bad else "FAIL " + " / ".join(bad))
    return 0 if not bad else 1

With an LLM you would have to write "do not include a style block" into the prompt every time and then eyeball the result. A script holds the rule in code, so it does not forget, and a pipeline only has to look at whether the exit code is 0. All four posts passed.

The first trap is CSS leaking across the whole site. Our blog renderer lifts style definitions found inside a post body up into the page-level head, so CSS written for one post can change others. The converter never emits a style block. It keeps a per-tag style dictionary and injects the styles inline:

import re

html = "<h2>Title</h2><p class='x'>Body</p><table><tr><td>cell</td></tr></table>"
S = {
    "h2": "font-size:1.5rem;font-weight:700;margin:2.4rem 0 .9rem;",
    "p":  "line-height:1.85;margin:0 0 1.05rem;",
    "td": "border:1px solid #e2e8f0;padding:.62rem .7rem;vertical-align:top;",
}
for tag, css in S.items():
    html = re.sub(rf"<{tag}(?=[ >])", f'<{tag} style="{css}"', html)
    html = html.replace(f"<{tag}>", f'<{tag} style="{css}">')

Tables are wrapped in an overflow-x:auto container in the same pass, so a wide table scrolls instead of pushing the whole page sideways on mobile.

The second trap was duplicated JSON-LD, and it came from the handoff document, not from the script. The spec said to put a BlogPosting block in the body. The front end already generates BlogPosting in the head, so following the spec literally would have produced duplicate structured data. Reading the receiving code while building the converter showed that only a FAQPage block belonged in the body.

The lesson is about order, not about this spec: read the receiving code before executing a handoff document. A spec is true as of the day it was written, and the system on the other side may have changed since.

A deterministic converter is only deterministic if the input follows the spec. Otherwise it silently drops things.

Failure condition Symptom Fix
FAQ heading differs faq_count is 0 Rename the H2 in the manuscript
Q/A pairs with no blank line between them Several pairs merge into one Add a blank line between pairs
No H1 Exit code 1, "no H1 title" Put a # Title on the first line
Manuscripts arrive in different formats each time The rules do not hold Agree on a format first, or keep a human on this step

Some limits are worth stating plainly. This converter is built for our blog platform. The per-tag inline styles and the "no style block" rule exist because our renderer hoists styles globally, and another platform may not have that constraint. Markdown parsing relies on an external library and its extensions (tables, sane_lists, nl2br), so a version change can alter the output. And the approach only fits steps that need no judgment: writing the manuscript is still the LLM's job. Split a publishing pipeline along that line, with evidence gathering, machine verification, and layout in scripts and first drafts from the LLM.

The original write-up, including the pre-publish checklist for manuscripts and converter output, is here: the full post on my-blog.org.

Free tools I keep on my own site: 34 calculators and how-to guides - loans, severance pay, take-home salary, savings vs deposits. New ones go out in one email, no ads.

── more in #structured-data 4 stories · sorted by recency
── more on @claude code 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/markdown-to-html-0-l…] indexed:0 read:6min 2026-11-20 · —