ruby是古籍数字化中唯一能语义化绑定“字-音-义”的原生方案，须人工校对到位、字体结构合规才生效，竖排下自动定位注音，需显式书写rb/rt、慎用于合文重文、多音字须分层写死以保障可维护性与导出质量。
ruby 标签在古籍整理中不是“加分项”，而是解决真实排版断层的关键工具——但它只在人工校对到位、字体与结构合规的前提下才真正生效。
古籍竖排文本里，ruby 是唯一能语义化绑定“字-音-义”的原生方案
古籍数字化常需为生僻字、通假字、异体字加注音（如《说文解字》引文中的古音）或训读（如日藏汉籍里的“振り仮名”）。用 span + title 或纯 CSS 模拟上标，会导致：语音朗读器跳过注音、打印时错位、缩放后拼音压字。而 ruby + rb + rt 的组合，让浏览器明确知道“这个音属于这个字”，尤其在竖排（writing-mode: vertical-rl）下，rt 会自动出现在右侧，无需手动计算偏移。
实际使用中要注意：
- 必须显式写
<rb>?</rb><rt>yǐ</rt>，不能省略rb—— 否则 Safari 17+ 和 Chrome 120+ 会降级为行内文本，拼音贴在字右边而非上方/右方 - 古籍常见合文（如「卍」、「龜」的异体）、重文符号（々），不能直接套
ruby；需先拆解为单字再标注，否则语义断裂 - 若用注音符号（ㄅ～ㄿ）而非拼音，要确认字体支持：macOS 的
PingFang TC、Windows 的Microsoft JhengHei可靠，但旧版SimSun缺「ㄖ」「ㄥ」等字形
多音字与训读混排时，ruby 结构决定校对可维护性
古籍中一字多音极常见（如「行」在「道行」中读 xíng，在「行伍」中读 háng），且常需同时标注反切（「户庚切」）和今音（「háng」）。这时不能靠 JS 动态注入，而应由校对员人工拆字并分层写死：
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
立即学习“前端免费学习笔记（深入）”；
<ruby><rb>行</rb><rt>xíng</rt></ruby>伍 <ruby><rb>行</rb><rt>háng</rt></ruby>伍
这种写法看似冗余，但好处是：
- 版本比对工具（如 git diff）能精准定位哪一字的注音被修改，而非整段重写
- 导出为 EPUB 或 PDF 时，排版引擎（如 PrinceXML）能正确识别 ruby 语义，生成带注音的固定布局
- 避免用
data-pinyin等自定义属性——它们不被任何阅读器解析，等于白标
兼容性短板在古籍项目里反而容易绕过
IE 不支持 ruby 是事实，但古籍数字化成果通常不面向 IE 用户交付。真正要处理的是两类降级场景：
- 邮件客户端（Outlook Desktop）或部分 PDF 转换器会丢弃
rt，只留基字 → 解决方案是在rt内嵌rp，例如：<rt><rp>(</rp>hàn<rp>)</rp></rt>，降级后显示为「汉(hàn)」，虽不美观但可读 - 安卓 WebView（尤其旧版）可能不渲染
rt→ 可用@supports not (display: ruby)做 CSS 降级，把rt设为font-size: 0.8em; position: relative; top: -0.5em;模拟效果 - 不建议用 JS 检测
ruby支持再动态插入——古籍页面常禁用 JS，且 SSR 渲染时无法执行检测逻辑
最易被忽略的一点：古籍 OCR 后的文本清洗阶段，如果把「『』」这类引号或「／」这类顿号误识别为汉字并套上 ruby，会导致结构污染。校对流程中必须在标注前做一次字符白名单过滤（只允许 Unicode CJK 统一汉字 + 注音符号 + 常用标点），否则后期排查成本远高于初期预防。
