Build markdown documents to HTML in the CI workflow (w3c#13432)

sideshowbarker · web-flow · commit 0a496e6aa72e · 2026-02-03T15:13:02.000-08:00
Add a build step that converts .md files in spec directories (explainers, transition documents, proposals, etc.) to HTML so they're served from GitHub Pages. The legacy draft server that previously handled this conversion is struggling with ~60% uptime. Relates to w3c#12054
diff --git a/.github/workflows/build-specs.yml b/.github/workflows/build-specs.yml
@@ -33,7 +33,7 @@ jobs:
           python-version: "3.14"
           cache: 'pip'
 
-      - run: pip install bikeshed
+      - run: pip install bikeshed markdown
       - run: bikeshed update
 
       # The following chunk of code all stolen from andeubotella
@@ -63,6 +63,8 @@ jobs:
             echo "  $file"
             bikeshed issues-list "$file" || true
           done
+      - name: Build markdown
+        run: python ./bin/build-markdown.py
       - name: Build index & symlinks
         run: python ./bin/build-index.py
       - run: rm -rf ./.git{,attributes,ignore}
diff --git a/bin/build-markdown.py b/bin/build-markdown.py
@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+"""Convert markdown files in spec directories to HTML."""
+
+import glob
+import os
+import re
+
+import markdown
+
+TEMPLATE = """\
+<!doctype html>
+<meta charset="utf-8">
+<title>{title}</title>
+<style>
+body {{ max-width: 50em; margin: 2em auto; padding: 0 1em; font-family: sans-serif; line-height: 1.6; }}
+code {{ background: #f4f4f4; padding: .1em .3em; border-radius: 3px; }}
+pre {{ background: #f4f4f4; padding: 1em; overflow: auto; border-radius: 3px; }}
+pre code {{ background: none; padding: 0; }}
+img {{ max-width: 100%; }}
+</style>
+{body}
+"""
+
+
+def extract_title(text):
+    m = re.search(r"^#\s+(.+)", text, re.MULTILINE)
+    return m.group(1).strip() if m else "Untitled"
+
+
+def main():
+    md = markdown.Markdown(extensions=["fenced_code", "tables"])
+
+    for md_file in sorted(glob.glob("*/*.md")):
+        if md_file.startswith("."):
+            continue
+
+        html_file = os.path.splitext(md_file)[0] + ".html"
+        if os.path.exists(html_file):
+            continue
+
+        with open(md_file, encoding="utf-8") as f:
+            text = f.read()
+
+        title = extract_title(text)
+        body = md.convert(text)
+        md.reset()
+
+        with open(html_file, "w", encoding="utf-8") as f:
+            f.write(TEMPLATE.format(title=title, body=body))
+
+        print(f"  {html_file}")
+
+
+if __name__ == "__main__":
+    main()
