Small e-commerce teams usually inherit their documentation from a theme: product descriptions in a database, policy pages in a CMS editor, and no version control anywhere. We moved our guides and policy drafts to a markdown-first workflow, and it changed how often the content actually gets updated. Here is the setup, honestly evaluated.
The pipeline
Content starts as plain markdown files in a git repository - one file per guide, front-matter for title and last-reviewed date. A tiny Python script checks each file for forbidden claims (we maintain a blocklist of words we never use in policy or educational pages), verifies every internal link with an HTTP check, and renders HTML for static endpoints.
What this fixed
Three things. First, link rot: product slugs change, and a build-time HTTP check fails the pipeline when an anchor dies, instead of a customer finding a 404 six months later. Second, review debt: the last-reviewed date in front matter makes stale pages visible in a single file listing. Third, tone consistency: a blocklist check at build time is more reliable than any style guide document, because it cannot be forgotten under deadline pressure.
What it did not fix
Anything visual. Comparisons, tables with images, anything layout-sensitive still needs the CMS. We kept the CMS for those pages rather than forcing markdown to do a job it is bad at. The worst early mistake was trying to encode a comparison table in markdown - it rendered badly on two mobile viewports and we reverted it within a week.
The cost
A build script, a link checker, and one CI job. Perhaps two days of work total, most of it spent writing the blocklist with legal care rather than on code.
The consumer-facing result of that pipeline is our learning library and the care guide; the build discipline behind them is invisible there, which is the point.
Disclosure: this article is published by our team account; content written with AI assistance, reviewed by a human before posting.
Top comments (0)