markdown.markdown() 默认仅支持基础语法，表格、目录等功能需手动启用 "tables" 和 "toc" 等扩展；否则 |a|b| 渲染为纯文本，[toc] 不生成目录，标题也无锚点id。

直接用 markdown 库的 markdown() 函数就能转，但默认不支持表格、代码高亮、目录等常见扩展，必须手动启用扩展才能正常渲染。

为什么 markdown.markdown() 转出来的 HTML 没有表格或标题锚点

因为 markdown 库默认只启用基础语法（如标题、列表、强调），像表格（tables）、自动目录（toc）、代码块语法高亮（需配合 pygments）都属于可选扩展，不显式传入就不会生效。

• 常见缺失现象：| 列1 | 列2 | 渲染成纯文本，不是 <table>；<code>[TOC] 不生成目录；```python 块没 class="highlight"
• 扩展名必须是字符串，比如 "tables"、"toc"、"fenced_code"（启用 ``` 代码块）
• 扩展顺序无关，但部分扩展有依赖，例如 "toc" 需要 "extra" 或单独启用（新版推荐直接用 "toc"）

怎样启用表格和目录扩展

把扩展名作为 extensions 参数传给 markdown.markdown()，类型是列表。注意 "toc" 扩展会自动为标题添加 id 属性，方便锚链接跳转。


Markdown → 图片卡片
当用户想要将Markdown内容转换为可分享的图片卡片时使用。触发词包括：转图片、做卡片、生成海报、生成分享图、把这个转成图片、export as image
下载

import markdown
md_text = "# 标题\n\n| A | B |\n|---|---|\n| 1 | 2 |\n\n[TOC]"
<p>html = markdown.markdown(md_text, extensions=["tables", "toc"])</p><h1>输出包含 </h1>

和
...
• "tables"：必须加，否则竖线语法被忽略
• "toc"：加了才解析 [TOC] 并生成目录 HTML；若想自定义标题文字，用 extension_configs={"toc": {"title": "目录"}})
• 如果用 ## 子标题 但没出现在 TOC，检查是否漏了 "toc"，或标题层级被 toc_depth 限制（默认只到 h6）

遇到中文乱码或空行渲染异常怎么办

本质是输入文本编码或换行符问题，markdown 库本身不处理编码，只按 Python 字符串处理。空行异常多因混用了 \r\n 和 \n，或开头/结尾有不可见 Unicode 空格。

• 读文件时务必指定 encoding="utf-8"：with open("a.md", encoding="utf-8") as f: md_text = f.read()
• 避免用 .strip() 粗暴清理，它会删掉缩进代码块需要的空格；改用 .replace("\r\n", "\n").replace("\r", "\n") 统一换行符
• 若输出 HTML 中中文显示为方框，说明浏览器没加载中文字体，和 markdown 无关；可在 CSS 加 body { font-family: "Microsoft YaHei", sans-serif; }
• safe_mode 参数已弃用（v3.0+），别再用，改用 extensions=["extra"] 启用更安全的 HTML 过滤逻辑

要不要用 markdown-it-py 或 mistune 替代

如果你只需要标准 CommonMark 兼容、速度更快、或明确要求无扩展依赖，markdown-it-py 是更现代的选择；但如果你项目已用 markdown 库、且只需补几个扩展，没必要换——markdown 的扩展生态成熟，文档清晰，"fenced_code" + pygments 就能搞定语法高亮。

• markdown 的 "fenced_code" 扩展只生成 <pre class="brush:php;toolbar:false;">&lt;code class=&quot;python&quot;&gt;&lt;/code&gt;，高亮需额外调用 &lt;code&gt;pygments.highlight()&lt;/code&gt;</pre>
• markdown-it-py 默认支持 CommonMark，开箱即用表格、疏松列表，但插件机制不同，迁移成本存在
• 真正容易被忽略的是：扩展启用后，HTML 输出不含任何 CSS，样式要自己写或引入 github-markdown-css 类似方案

Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！