markdown-static-site-source

Markdown as the source of truth for a JS-data-driven static site

When to use

• A static site (plain HTML/CSS/JS, no build framework) renders content from a data object in a JS file, e.g. window.PORTFOLIO_DATA = {...} consumed by a render script (main.js) that builds the DOM.
• The user wants to edit content in Markdown / Obsidian and have the site update, WITHOUT touching the HTML/template/CSS.
• The render must stay EXACTLY the same (pixel/semantics identical to today).

Core idea

Find the "data seam": the single JS object the render engine reads. Make a Markdown file with YAML frontmatter the SOURCE OF TRUTH. Write a tiny generator that emits that same JS object. The render engine never changes → output is identical by construction. Verify the emitted object is semantically equal to the original, NOT byte-equal (formatting differs, meaning must not).

Steps

1. Locate the data object. Grep for window.<X> = / const PORTFOLIO_DATA. Confirm what consumes it (e.g. main.js reads window.X and builds DOM).
2. Snapshot the original data file to *.orig — this is your verification baseline.
3. (Optional, one-time) seed.js: load the original JS (shim window / module.exports), dump the parsed object to a YAML-frontmatter MD. Freezes today's content as the source.
4. build.py: read the MD, emit valid JS reconstructing the SAME object:
   • Serialize with a real JS-literal emitter (objects/arrays as {}/[], strings double-quoted with \" and \n escapes). Do NOT emit YAML — the browser must evaluate it.
   • Preserve structure exactly: same keys, same nesting, same field order where the consumer relies on it.
   • Resolve constants: if the original referenced variables inside the data (e.g. "https://orcid.org/" + ORCID), inline the values so the generated object equals the original at runtime.
   • For i18n, mirror the EXACT nesting of the original (e.g. bolsas may nest i18n.en = {title,kind,desc} per language). Match it; don't transpose unless you also change the consumer.
5. verify.js (Node): load BOTH the generated file and *.orig via new Function('window', src + 'return window.X'), then deep-equal the objects. Exit 1 on diff. This is the real test — a byte diff will always show false positives.
6. Pre-commit hook: run build.py so git commit always recompiles; git add the generated file.
7. User workflow: edit src/<site>.md in Obsidian → python3 tools/build.py → git add -A && git commit && git push.