Markdown 轉 HTML:4 篇文章零 LLM tokens,擷取 23 條 FAQ
Markdown to HTML: 0 LLM Tokens for 4 Posts, 23 FAQs Extracted
作者用確定性轉換器將 4 篇共 43,699 bytes 的 Markdown 稿件轉成 HTML,沒有消耗 LLM tokens,並自動擷取 23 條 FAQ,四篇均通過內置檢查。
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.
Three questions that decide script versus LLM
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.
What the converter does
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 extraction: the manuscript spec is the parser spec
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.
Self-checks as exit codes
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.
Two traps the script closed
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.
When this breaks
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.
來源:DEV Community · dev.to

