> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 渲染行为

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

## 段落、文本与格式

- 连续行内内容聚合为 `<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` 等名称。

## 链接

| 类型                        | 默认输出                                         |
| ------------------------- | -------------------------------------------- |
| 内部链接 `[[Page]]`           | 无法导航的 `<span class="wtr-link">`，`title` 为页面名 |
| 带标签外链 `[https://… label]` | 经过安全校验的 `<a>`，带 `rel` 与 `target`             |
| 裸外链 `https://…`           | `<a>`，标签为 URL 文本                             |
| 无标签外链 `[https://…]`       | 按文档顺序生成 `[N]`，编号独立于引用                        |

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

外部链接默认 `target="_blank"`、`rel="nofollow noopener noreferrer"`；可通过 `policy.externalLinkTarget` 或解析函数返回的 `target` 调整。细节见[链接与图片](/zh/guide/links-and-images.md)。

## 文件与图片

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

```html
<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`](/zh/guide/templates.md)。展开失败而保留的调用仍然按占位渲染。

## 参考文献

- 每个 `<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。完整规则见[安全模型](/zh/guide/security.md)。

## 扩展标签

| 标签                                                                           | 当前行为                                         |
| ---------------------------------------------------------------------------- | -------------------------------------------- |
| `<nowiki>`                                                                   | 纯文本，不解析链接或模板                                 |
| `<pre>`                                                                      | 保留原始空白                                       |
| `<ref>`                                                                      | 分组编号引用 + 引用区                                 |
| `<references>`                                                               | 占位；最终整理把对应分组引用区放到该位置                         |
| `<math>`                                                                     | `<code>` 公式源码占位，不引入 KaTeX                    |
| `<syntaxhighlight>`                                                          | `<pre><code class="language-*">` 原始文本，不接语法高亮 |
| `<poem>`                                                                     | 按空行分段，段内换行输出 `<br>`                          |
| `<gallery>`                                                                  | 经 `resolveImage` 出图，否则显示文件名                  |
| `<imagemap>`、`<templatestyles>`、`<chem>`、`<score>`、`<timeline>`、`<mapframe>` | 块级源码卡片                                       |
| 其他未专门支持的扩展                                                                   | 源码卡片；独立成行时按块级展示                              |

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

## 未知结构与降级

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

## 无障碍

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

- 根容器只设置调用方传入的 `lang` 与 `dir`；缺省时继承宿主。
- 标题使用真实的 `<h1>`–`<h6>`，锚点策略见[样式与组件](/zh/guide/customization.md)。
- 目录是带 `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`。
- 没有经过屏幕阅读器测试或无障碍合规认证；宿主应按目标标准自行验证。

## 稳定限制

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

| 限制             | 说明                                         |
| -------------- | ------------------------------------------ |
| 模板与 Lua 不执行    | 默认只占位；`/expand` 仅支持纯 wikitext 模板与受支持的解析器函数 |
| 图片默认不加载        | 需要宿主通过图片解析函数授权                             |
| 嵌套 wikitext 表格 | 整表降级；HTML `<table>` 嵌套可渲染                  |
| 引用分组/回链        | 支持命名复用、`group` 分组与 `<references/>` 位置      |
| 重复引用定义         | 保留第一次内容，并产生诊断                              |
| 行首空格           | 按普通文本处理，不提供预格式化语义                          |
| 目录能力有限         | 不滚动联动、不折叠、不吸顶                              |
| 同步解析预算         | 100 KB 级密集文本可能阻塞主线程；需要 Worker              |
| 无编辑器 SDK       | 不包含 CodeMirror、编辑事务、双向选区或源码重写              |
| 无虚拟列表          | 大文档依赖调用方分页或 Worker 调度                      |

遇到与默认行为不符的输出，先看[故障排查](/zh/guide/troubleshooting.md)。