Markdown转HTML需手动注入CSS或用mkdocs等工具；默认无样式、不支持数学公式等扩展，须显式启用extensions；路径处理要防乱码和404；推荐python-markdown+jinja2+CSS或mkdocs批量渲染。
用 markdown 库转出基础 HTML，但默认样式极简
直接调用 markdown.markdown() 能把 .md 文件转成纯 HTML 字符串，但结果只有语义标签（<h1>、<p>、<ul> 等），没 CSS，浏览器打开就是白底黑字、无缩进、无行距——根本谈不上“排版美观”。
常见错误是以为转换完成就结束了，结果生成的 HTML 在不同设备上字体大小一致、代码块没高亮、表格没边框。
- 必须手动注入 CSS，或使用支持主题/模板的封装库
-
markdown默认不解析数学公式、目录、脚注等扩展，需显式启用extensions - 路径处理容易出错：读取时用
open(file_path, encoding="utf-8")，否则中文乱码；写入时确保输出目录存在，否则FileNotFoundError
用 mkdocs 或 mdbook 做批量渲染更省心
如果你要批量处理几十个 Markdown 文件，并希望统一导航栏、侧边目录、深色模式、响应式布局，硬写 Python 脚本反而低效。此时 mkdocs 是更合理的选择——它专为文档站点设计，命令一行就能生成整站 HTML：
mkdocs build
它会自动扫描 docs/ 下所有 .md 文件，应用默认主题（Material for MkDocs 最常用），生成带 JS 交互的静态页面。
立即学习“Python免费学习笔记（深入）”；
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
- 不需要写 Python，但需配置
mkdocs.yml：指定site_name、theme、nav结构 - 支持插件：加
mkdocs-material得到现代化 UI；加mkdocs-table-reader可从 CSV 渲染表格 - 注意文件名和路径：MkDocs 默认只处理
docs/子目录下的文件，且首页必须叫index.md
用 python-markdown + 自定义 CSS 模板精细控制每一页
若你坚持手写 Python 脚本（比如要嵌入公司内部样式、动态插入页脚、或与现有 Flask 服务集成），推荐组合：markdown 解析 + jinja2 渲染模板 + 外部 CSS 文件。
关键不是“怎么转”，而是“怎么包进 HTML 骨架”。示例流程：
- 读取
input.md→markdown.markdown(text, extensions=["fenced_code", "tables", "toc"]) - 用
jinja2.Template加载一个含<link rel="stylesheet">的 HTML 模板 - 将解析后的 HTML 片段作为变量传入模板，
render(content=html_content) - 输出到
output.html，确保 CSS 文件路径正确（建议用相对路径如./style.css）
容易忽略的一点：toc 扩展生成的目录是 HTML 片段，不含 JS 锚点滚动逻辑——如需点击目录跳转，得额外加 <script> 或用 toc_depth 参数控制层级。
图片、链接、代码块的路径和渲染必须单独处理
Markdown 中的  或 [link](doc.md) 在转成 HTML 后，路径仍是原始相对路径。如果输出 HTML 放在 dist/ 目录，而图片在 src/assets/，浏览器会 404。
- 方案一：用正则预处理原文本，把
替换为（适合固定结构） - 方案二：用
markdown的extension_configs配合自定义ImagePreprocessor类重写路径 - 代码块高亮依赖
pygments：启用fenced_code后，加上codehilite扩展，并用pygments_style="github-dark"控制配色
最常卡住的地方不是语法转换，而是资源路径错位和 CSS 选择器没覆盖到生成的 class 名（比如 codehilite 输出的 <pre><code class="python">，你的 CSS 必须匹配这个 class）。
