#渲染行为

本文描述默认管线实际会输出什么。库不会为了外观相似而推断语义：无法安全或正确表达的结构会明确降级为源码卡片或占位。如果只想查某段语法会被怎么处理，见支持矩阵。

#段落、文本与格式

• 连续行内内容聚合为 <p class="wtr-paragraph">；两个及以上空行切分段落，单个换行折叠为空格。
• 粗体、斜体来自 MediaWiki 引号语法，输出 <b> / <i>；粗斜同时开启时为 <i><b>…</b></i>。
• 标题输出真实 <h1>–<h6 class="wtr-heading">，并参与标题锚点与目录。
• 水平线输出 <hr class="wtr-hr">。
• 注释、分类与行为开关不进入正文；分类汇总到文末底栏，行为开关只影响目录。

#列表

• *、#、;、: 前缀生成嵌套的 <ul>、<ol>、<dl>/<dt>/<dd>。
• 续行会并入当前列表项；空行、标题、表格、块级 HTML 等结束列表。
• 定义列表支持 ; term : definition 与 ;term:definition。
• 单元格内的列表扫描受单元格范围限制，不会把下一个单元格并入列表。

#表格

• 输出顺序为 <table><caption>…</caption><tbody>…；单元格使用 <th> / <td>。
• 表格、行、单元格属性按白名单保留；style 只保留安全排版子集，事件属性与 id 始终丢弃。
• 布局按逻辑网格计算：colspan / rowspan 会被限制在表格范围内，未被占用的位置会生成填充单元格（wtr-table__cell--filler）。
• wikitext 嵌套表格当前整表降级为源码卡片；HTML <table> 嵌套可以正常渲染。
• 表格属性允许安全的 data-*，但拒绝库保留的 data-node-id、data-wikitext 等名称。

#链接

内部链接只有在 resolveLink 返回 href 时才生成 <a>。外链只允许 http:、https:、mailto:，协议相对地址会补上 https:；javascript:、data: 等会被拦截并显示为可读文本。

外部链接默认 target="_blank"、rel="nofollow noopener noreferrer"；可通过 policy.externalLinkTarget 或解析函数返回的 target 调整。细节见链接与图片。

#文件与图片

文件节点默认输出占位结构：

<figure class="wtr-file wtr-file--block mw-default-size">
  <span class="wtr-file__label">File: Example.png</span>
  <figcaption class="wtr-file__caption">说明文字</figcaption>
</figure>

• 行内文件用 <span class="wtr-file">，块级用 <figure>。
• 说明文字来自真实子树，内部链接与模板占位会递归渲染。
• 只有 resolveImage 返回 src 且通过 http: / https: 校验时才生成 <img loading="lazy" decoding="async">；宽高限制在 1–4096。
• 库不访问 upload.wikimedia.org 或任何图片地址。

#模板、函数与参数

默认管线不求值：

• 模板：块级 <details class="wtr-template"> 或行内徽标，列出参数；文案来自 labels.templateNotExpanded。
• 解析器函数：同样是占位结构，明确标记为未求值。
• 参数 {{{name|default}}}：显示参数名与默认值。
• 模板、函数与参数中的魔术字不参与目录与分类判断。

需要展开时使用 /expand。展开失败而保留的调用仍然按占位渲染。

#参考文献

• 每个 <ref> 在所属分组内按渲染顺序编号，生成 <sup class="reference wtr-ref"> 与编号链接。
• 引用内容汇总为 <section class="wtr-references" role="doc-endnotes">；命名引用复用同一条目，分组各自编号。
• <references/> 或 <references group="x"/> 决定对应分组引用区的位置；没有占位的分组追加在正文之后、分类底栏之前。注释项带回链 a[role="doc-backlink"]。
• 重复定义与空引用产生诊断；同一注释被多次引用时，上标 id 依次为 cite_ref-N、cite_ref-N-2。

#目录

• 同页标题达到 4 个时自动生成目录，放在首个标题所在的顶层块之前（标题可以在块级 HTML 内）。
• 准备选项 toc 可以调整 minHeadings、columns 或设为 false 关闭目录。
• __TOC__ 在标记位置强制生成目录；__FORCETOC__ 强制自动目录；__NOTOC__ 在任何位置关闭目录，优先级更高。
• 目录包含层级、编号、文本与 #锚点 链接；片段敏感字符会编码为 .HH，headingIdStrategy: "none" 时不生成链接。
• 目录不提供滚动联动、折叠或吸顶。

#分类与重定向

• 分类不进入正文，按源码顺序汇总到文末 div.catlinks.wtr-categories；分类名去掉命名空间前缀，下划线显示为空格，排序键不显示。
• 首行 #REDIRECT 渲染为重定向横幅并跳过后续正文，不自动加载目标页。

#HTML

源码 HTML 不会作为原始 HTML 注入。库按类别处理：

• 行内标签：b、i、u、span、code、ruby、abbr 等。
• 块级标签：div、p、blockquote、center、pre、列表、表格、标题等。
• 空元素（void）：br、wbr、hr。
• 丢弃：meta、link。
• 禁止：script、style、iframe、object、embed、表单控件、svg、HTML 版 math 等。默认配置不解析这些标签，源码会作为纯文本转义；若被配置纳入 HTML 解析，整对内容会被丢弃并显示可读提示。
• 未知但非危险标签：显示源码卡片，不渲染为真实元素。

HTML 属性只保留白名单中的 class、title、dir、lang、安全 style 与表格相关属性；id、事件属性不会进入 DOM。完整规则见安全模型。

#扩展标签

semanticComponents.extension 可以按标签名自定义这些扩展结构；<ref> 走 semanticComponents.reference，<references> 不产生组件调用。

#未知结构与降级

未识别的语义节点、无法配对的复杂 HTML、嵌套 wikitext 表格等会显示为源码卡片，并在诊断中记录。一个块渲染失败时，错误边界只替换该顶层块，其他内容继续渲染；onRenderError 可以上报失败节点。

#无障碍

库输出语义化结构，但不提供完整的无障碍层：

• 根容器只设置调用方传入的 lang 与 dir；缺省时继承宿主。
• 标题使用真实的 <h1>–<h6>，锚点策略见样式与组件。
• 目录是带 aria-label 的 nav，文案来自 labels.toc。
• 引用区是 section[role="doc-endnotes"]，引用链接带“引用 N”的 aria-label，注释项带回链。
• 分类区带 role="navigation" 与可见的分类标签；表格 <th> 缺省补 scope="col"。
• 图片的 alt 依次取 resolveImage 的 alt、alt= 参数、说明文字或文件名。
• 部分提示（被拦截的 HTML、降级表格、重定向）使用 role="note" 的文本。
• 库不管理焦点、不提供跳转链接或实时区域；多实例页面应固定 idPrefix。
• 没有经过屏幕阅读器测试或无障碍合规认证；宿主应按目标标准自行验证。

#稳定限制

以下限制来自解析器能力或项目边界，不会随开发推进消失：

遇到与默认行为不符的输出，先看故障排查。