Skip to content

Build markdown documents to HTML in the CI workflow #13432

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tabatkins merged 1 commit into from
Feb 3, 2026
Merged

Build markdown documents to HTML in the CI workflow #13432

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .github/workflows/build-specs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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}
Expand Down
55 changes: 55 additions & 0 deletions bin/build-markdown.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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()