#!/usr/bin/env python3 """把 docs/ARCHITECTURE_SYSTEM.md 渲染成自包含、可分享的单文件 HTML。 设计约束(与项目「判定口径只有一份实现」一致): * md 是唯一真相源,HTML 是**派生产物,勿手改**; * 输出不含外部资源(CDN / 字体 / JS),离线双击即可看,也可直接分享; * 生成结果幂等:不写时间戳,重复生成不产生 diff 噪音; * `--check` 用于校验 HTML 是否与 md 同步(改了 md 忘记重新生成会被抓到)。 用法: python3 tools/render-share-html.py # 生成 python3 tools/render-share-html.py --check # 只校验,不写文件 python3 tools/render-share-html.py --input X --output Y 依赖:markdown-it-py(本机已装)。缺失时明确报错,绝不静默跳过。 """ from __future__ import annotations import argparse import html import re import sys from pathlib import Path REPO = Path(__file__).resolve().parent.parent DEFAULT_INPUT = REPO / "docs" / "ARCHITECTURE_SYSTEM.md" DEFAULT_OUTPUT = REPO / "docs" / "ARCHITECTURE_SYSTEM.html" try: from markdown_it import MarkdownIt except ImportError: sys.exit( "缺少 markdown-it-py:请先 `python3 -m pip install markdown-it-py`。\n" "本脚本不静默降级 —— 半渲染的 HTML 比没有 HTML 更危险。" ) CSS = r""" :root{ --bg:#f7f8fa; --surface:#ffffff; --ink:#1b1f24; --muted:#5b6572; --line:#e3e7ec; --accent:#2563a8; --accent-soft:#eaf2fb; --code-bg:#f2f4f7; --quote-bg:#f4f8fd; --warn-bg:#fff7e8; --warn-line:#e0a336; --mono:ui-monospace,SFMono-Regular,Menlo,Consolas,"Liberation Mono",monospace; --sans:-apple-system,BlinkMacSystemFont,"PingFang SC","Hiragino Sans GB", "Microsoft YaHei","Segoe UI",Roboto,sans-serif; } @media (prefers-color-scheme:dark){ :root{ --bg:#14171c; --surface:#1b2027; --ink:#e6e9ee; --muted:#9aa5b3; --line:#2c333d; --accent:#79b8ff; --accent-soft:#1c2c3e; --code-bg:#20262f; --quote-bg:#1a2532; --warn-bg:#33291a; --warn-line:#b8842f; } } *{box-sizing:border-box} html{scroll-behavior:smooth} body{margin:0;background:var(--bg);color:var(--ink);font-family:var(--sans); font-size:15.5px;line-height:1.75;-webkit-font-smoothing:antialiased} .layout{display:flex;gap:0;max-width:1320px;margin:0 auto;align-items:flex-start} nav.toc{position:sticky;top:0;flex:0 0 268px;width:268px;height:100vh;overflow-y:auto; padding:28px 18px 40px 24px;border-right:1px solid var(--line);background:var(--surface)} nav.toc .brand{font-weight:700;font-size:15px;letter-spacing:.02em;margin-bottom:4px} nav.toc .sub{font-size:12px;color:var(--muted);margin-bottom:20px} nav.toc a{display:block;color:var(--muted);text-decoration:none;font-size:13px; padding:5px 8px;border-radius:5px;border-left:2px solid transparent} nav.toc a:hover{color:var(--accent);background:var(--accent-soft)} nav.toc a.lv3{padding-left:22px;font-size:12.5px;opacity:.9} main{flex:1 1 auto;min-width:0;padding:30px 40px 90px;background:var(--bg)} .banner{background:var(--warn-bg);border-left:3px solid var(--warn-line); padding:10px 14px;border-radius:0 6px 6px 0;font-size:13px;color:var(--ink); margin-bottom:26px} .banner code{font-family:var(--mono);font-size:12px} article{background:var(--surface);border:1px solid var(--line);border-radius:10px; padding:34px 40px 48px;box-shadow:0 1px 3px rgba(0,0,0,.04)} article h1{font-size:27px;line-height:1.35;margin:0 0 22px;padding-bottom:14px; border-bottom:2px solid var(--accent)} article h2{font-size:20px;margin:38px 0 14px;padding-top:10px; border-top:1px solid var(--line)} article h3{font-size:16.5px;margin:26px 0 10px;color:var(--accent)} article h1:first-of-type{border-top:0} article p{margin:10px 0} article a{color:var(--accent);text-decoration:none;border-bottom:1px solid var(--accent-soft)} article a:hover{border-bottom-color:var(--accent)} article strong{font-weight:650} article hr{border:0;border-top:1px solid var(--line);margin:30px 0} article blockquote{margin:16px 0;padding:10px 18px;background:var(--quote-bg); border-left:3px solid var(--accent);border-radius:0 6px 6px 0; color:var(--ink)} article blockquote p{margin:6px 0} article ul,article ol{padding-left:24px;margin:10px 0} article li{margin:4px 0} article code{font-family:var(--mono);font-size:.88em;background:var(--code-bg); padding:1px 5px;border-radius:4px;word-break:break-word} article pre{background:var(--code-bg);border:1px solid var(--line);border-radius:7px; padding:16px 18px;overflow-x:auto;line-height:1.55;margin:16px 0} article pre code{background:none;padding:0;font-size:12.6px;white-space:pre} article table{display:block;width:100%;overflow-x:auto;border-collapse:collapse; margin:16px 0;font-size:13.8px} article th,article td{border:1px solid var(--line);padding:8px 11px;text-align:left; vertical-align:top;min-width:80px} article th{background:var(--accent-soft);font-weight:650;white-space:nowrap} article tr:nth-child(even) td{background:rgba(127,140,160,.045)} article blockquote table{font-size:13px} footer{max-width:760px;margin:26px auto 0;color:var(--muted);font-size:12.5px;text-align:center} @media (max-width:900px){ .layout{display:block} nav.toc{position:static;width:auto;height:auto;border-right:0; border-bottom:1px solid var(--line);padding:18px 20px} nav.toc a{display:inline-block;margin:2px 4px 2px 0} nav.toc a.lv3{display:none} main{padding:20px 16px 60px} article{padding:22px 18px 32px} } @media print{ body{background:#fff;color:#000;font-size:11pt} nav.toc,.banner{display:none} main{padding:0} article{border:0;box-shadow:none;padding:0} article h2{page-break-after:avoid} article pre,article table,article blockquote{page-break-inside:avoid} a{color:#000;text-decoration:underline} } """ HTML_TEMPLATE = """ {title} · ssw-mpc
{body}
""" def render(md_text: str) -> tuple[str, str]: """返回 (标题, 完整 HTML)。""" md = MarkdownIt("commonmark").enable(["table", "strikethrough"]) rendered = md.render(md_text) title_m = re.search(r"

(.*?)

", rendered, re.S) title = html.unescape(re.sub(r"<[^>]+>", "", title_m.group(1))).strip() if title_m else "系统架构" headings: list[tuple[str, str, str]] = [] counter = [0] def add_ids(m: re.Match[str]) -> str: counter[0] += 1 level, inner = m.group(1), m.group(2) sec_id = f"sec-{counter[0]}" text = html.unescape(re.sub(r"<[^>]+>", "", inner)).strip() if level in ("2", "3"): headings.append((sec_id, level, text)) return f'{inner}' rendered = re.sub(r"(.*?)", add_ids, rendered, flags=re.S) toc = "\n ".join( f'{html.escape(text)}' for sec_id, level, text in headings if level in ("2", "3") ) return title, HTML_TEMPLATE.format(title=html.escape(title), css=CSS, toc=toc, body=rendered) def main() -> int: ap = argparse.ArgumentParser(description=__doc__) ap.add_argument("--input", type=Path, default=DEFAULT_INPUT) ap.add_argument("--output", type=Path, default=DEFAULT_OUTPUT) ap.add_argument("--check", action="store_true", help="只校验产物是否与 md 同步,不写文件") args = ap.parse_args() if not args.input.is_file(): sys.exit(f"输入不存在:{args.input}") md_text = args.input.read_text(encoding="utf-8") _, output = render(md_text) if args.check: if not args.output.is_file(): print(f"FAIL: 产物不存在 {args.output}") return 1 if args.output.read_text(encoding="utf-8") != output: print("FAIL: HTML 与 md 不同步,请运行 python3 tools/render-share-html.py") return 1 print(f"OK: HTML 与 md 同步({args.output.relative_to(REPO)})") return 0 args.output.parent.mkdir(parents=True, exist_ok=True) args.output.write_text(output, encoding="utf-8") print(f"OK: 已生成 {args.output.relative_to(REPO)}({len(output)} 字节,自包含)") return 0 if __name__ == "__main__": sys.exit(main())