必须与成对出现，因浏览器仅识别完整嵌套结构（为容器、为注音内容）作为注音语义；单独使用任一标签将被降级为纯文本，导致拼音不显示或错位。

直接用 包汉字、 放拼音，结构必须严格一对一——不是“词配音”，而是“字配音”，漏掉 或多字共用一个 就会渲染失败或语义丢失。

为什么 必须和 成对出现

浏览器只把完整嵌套结构识别为注音语义： 是容器， 是内容，缺一不可。单独写 汉 或 hàn汉，现代浏览器大多会忽略注音逻辑，降级为纯文本。

• 常见错误现象：拼音不显示、出现在基字后面、被截断、或整个 变成普通小字
• 根本原因常是 DOM 结构断裂，比如在 CMS 富文本中被自动过滤了 标签
• 验证方法：打开开发者工具，检查元素是否被渲染为 display: ruby（Chrome/Firefox）或 display: -webkit-ruby（Safari）

多字怎么处理：必须逐字包裹，不能偷懒

「你好」不能写成 你好nǐ hǎo，否则部分 Safari 和旧 WebView 会把拼音叠在「你好」整体上方，且屏幕阅读器无法分别朗读每个字的读音。

• 正确写法是 你nǐ好hǎo，或更规范地用 显式分隔：你nǐ好hǎo
• 不是可选的——它明确定义基字范围，在复杂排版（如竖排、行内换行）中能防止错位
• 避免用正则简单替换「所有汉字」加 ，遇到 emoji、全角标点、组合字符（如「ā」）可能破坏结构

拼音怎么填：格式、大小写、声调有硬约束

拼音必须用半角小写字母，推荐带 Unicode 声调符（如 hàn），而非数字标调（如 han4）。后者虽能显示，但语音合成器可能无法正确识别变调规则。

Convert Markdown To HTML And PDF - Markdown和HTML、PDF互转

实现 Markdown↔ HTML 互转，支持导出 PDF，用于用户请求的文档格式转换。

下载

• 禁用全角空格、中文冒号、连字符（如 nǐ-hǎo 或 nǐ：hǎo），会导致 内容被截断或错位
• 多音字必须按语境手动指定，pypinyin.lazy_pinyin() 默认返回常用音，不会自动判断「重」在「重庆」中读 chóng
• 轻声、儿化音要写完整，如「我们」标为 wǒ men，不是 wǒ mén；「一会儿」应拆为 yí huì ér，三字三

兼容性与样式控制的关键细节

现代浏览器（Chrome 110+、Firefox 115+、Safari 17+）已原生支持，但默认渲染差异大：Safari 对 缩放更激进（约 50%），Chrome 约 60%，Firefox 则依赖父级 font-size 继承。仅靠 font-size: 0.6em 不够稳定。

• 必须加内联样式：，避免外部 CSS 类冲突
• 禁用 line-height: 1 或 font-size: 0 等全局设置，否则 可能被裁掉顶部
• 移动端 Safari 不支持 ruby-position: under，只认 over（即默认上方），无需额外声明
• IE 完全不支持，若需兼容，得用 汉(hàn) + CSS 模拟，但语义和无障碍能力归零

最易被忽略的是 的显式使用和非汉字块的隔离处理——混排文本（如「第1章:Python入门」）里，数字、英文、标点必须跳过拼音生成，否则 结构会因空 或数量错位而崩坏。这不是语法问题，而是数据流断裂。