Markdown 标题链接模块契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | createMarkdownHeadingLinks(options?) 返回一个从 @astryxdesign/core/Markdown/plugins 导出的第一方条目。 |
| 行为 | 安装该条目后,每个渲染出的 h1–h6 都会获得一个确定性的、无冲突的 ID,并且每个内置标题都会附带一个行尾的 # 复制按钮。 |
| 最终用户影响 | 读者可以在不改变当前 hash、滚动位置或页面的情况下,复制持久的标题 URL 并获得即时确认;传入的 fragment URL 仍会定位到对应的标题 ID。 |
| 构建方影响 | 构建方显式安装一个条目,并可提供稳定的标题命名空间和安全的 URL 基础。该条目同时保持 Markdown 派生的 Outline ID 对齐且仅限根级。 |
| 兼容性 | 新增行为且默认关闭。没有此模块时,已发布的 Markdown/Outline 标题遍历、ID、DOM、样式以及自定义标题所有权均保持不变。 |
| 评审检查 | 拒绝默认开启的行为、Markdown prop、仅 Outline 的命名空间、运行时 ID、模块局部条目状态、未经验证的仿冒品、锚点/伪造链接、定制揭示逻辑、强加的自定义结构或产品形态的导航。 |
此表是一个评审投影;以下正文为准。
意图¶
发布文档的构建方应能选择使用可移植、持久的标题链接,而无需将产品身份或导航策略变成永久的 Markdown prop。该模块拥有一个完整的第一方组合:身份投影、永久链接复制按钮渲染、本地化以及跨界面证据。
兼容性与迁移¶
- 已发布的默认行为保留:
yes - 兼容性类别:新增且可选加入(opt-in)
- 迁移决策:
spec:AST-002/DEC-8 - 现有构建方无需做任何事。希望获得全深度标题身份的构建方只需创建一个稳定条目,并将其传给 Markdown 以及同一来源的任何 Outline 派生。
所有权边界¶
拥有
createMarkdownHeadingLinks()与MarkdownHeadingLinksOptions。- 稳定的内部插件名称,以及一个冻结的、带版本号、经过结构验证的配置,该配置由不透明条目在兼容的 Core 包副本间携带。
- NFKC Unicode slug 生成、回退、已发出 ID 的保留、命名空间组合,以及全深度后变换投影。
- 由 Markdown 和 Markdown 派生的 Outline 共同使用的 ID、标签、经过清理的永久链接基础,以及规范复制 URL。
- 内置同级复制按钮渲染器、
useContainerReveal组合、i18n、交互样式、Storybook 示例、SSR 证明和浏览器证据。
不拥有 / 非目标
- Markdown 的通用插件协议、解析器、变换顺序、默认标题样式,或已发布的无插件根级标题投影。
- Outline 的仅根级条目选择、hook API 或记忆化框架。
- 调用方自定义
components.heading的 DOM、样式、无障碍或永久链接 UI。 - 产品特定的文档身份、版本化、主机 URL 构造、查看器滚动、回调或路由。
公共 API 与概念¶
| 概念 | 封闭值或状态 | 含义 | 默认值 | 所有者 | 稳定性 |
|---|---|---|---|---|---|
createMarkdownHeadingLinks() |
一个返回 MarkdownPluginEntry<never> 的工厂函数 |
安装一个可移植的模块条目,兼容的 Core 副本可识别它。 | 缺省 | module:Markdown/headingLinks |
稳定 |
headingIdPrefix |
字符串或省略 | 调用方拥有的稳定命名空间,以 <prefix>--<slug> 形式前置。 |
无前缀 | 调用方 | 稳定 |
permalinkBaseUrl |
安全导航 URL 或省略 | 调用方拥有的基础 URL,其现有 fragment 会被生成的 fragment 替换。 | 当前文档 | 调用方 | 稳定 |
| 标题投影 | 缺省或已安装 | 缺省时使用已发布的仅根级身份;安装后使用模块拥有的全深度身份。 | 缺省 | 模块 | 稳定 |
| 内置复制控件 | 作为同级的真实 type="button" |
复制规范 URL 而不进行导航,并显示对勾 1.5 秒。 | 缺省 | 模块 | 稳定 |
| 自定义标题渲染器 | 调用方替换 | 仅接收生成的 ID,并保留对输出的完全所有权。 | 内置 | 调用方 | 稳定 |
行为契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| FR1 | 工厂函数和选项类型仅通过服务端安全的 @astryxdesign/core/Markdown/plugins 入口点导出。普通的 opaque(不透明)MarkdownPluginEntry<never> 在共享的、经结构校验的 Symbol.for 协议封装内携带一个冻结且带版本的模块配置,因此兼容的 Core 副本无需模块局部身份或状态即可识别它。 |
spec:AST-036 FR1–FR5, DEC-11 |
| FR2 | headingIdPrefix 和 permalinkBaseUrl 仅接受字符串,并随条目一起传递。URL 基础使用 Markdown 的导航清理器,拒绝不安全的 destination,并替换任何现有 fragment。使用者只识别完全兼容的模块配置。具有不兼容模块数据的有效同名泛型插件保持普通插件顺序,但不获得标题链接行为;格式错误的泛型条目遵循现有的 Markdown/Outline 故障软化路径。直接传入无效的工厂参数仍可能抛出异常。 |
family:navigation-destinations |
| FR3 | 转换后,每个层级的每个标题在文档顺序中恰好参与一次。标签使用规范的扩展文本投影。slug 使用 NFKC、小写 Unicode 字母/数字、移除引号、合并连字符,以及 section。 |
component:Markdown FR13, FR16 |
| FR4 | 每个生成的 ID 都被保留。自然数字后缀绝不会与早期生成的 ID 冲突或重新生成该 ID。 | 模块身份所有权 |
| FR5 | 省略该模块可保留已发布的根标题 ID、嵌套标题行为、DOM、样式、Outline 结果以及自定义渲染器的所有权。 | component:Markdown FR12 |
| FR6 | 将同一条目传递给 Markdown 和源自 Markdown 的 Outline 会共享同一个投影。嵌套标题会占用身份标识并参与冲突处理,而 Outline 继续只选择根标题。 | module:Outline/parseOutlineFromMarkdown |
| FR7 | 内置标题仍是一个语义化的 h1–h6,并增加一个名副其实的兄弟节点 type="button";自定义标题接收生成的 ID,且不会被强加包装器或控件。 |
component:Markdown FR2–FR3 |
| FR8 | 在同步 SSR、水合、多个命名空间实例、重排以及独立渲染中,ID 都是确定性的。 | 模块身份所有权 |
| FR9 | 公共入口保持服务器安全且可摇树优化;客户端渲染器对 Markdown 保持私有。产品标识、版本控制、滚动、回调、路由和宿主 URL 构造永远不会进入该模块。 | 包导出与副作用约定 |
| FR10 | 未经修改的点击、轻触、Enter 或 Space 会复制规范绝对 URL,且不会发生导航、滚动或哈希变更。成功时显示对勾和本地化的礼貌式播报,持续 1.5 秒;失败时保持静默。标题行使用规范的 useContainerReveal、按行高尺寸的流式布局、稳定的逻辑末尾间距、不重叠的 24px 粗指针命中区域,以及一个仅键盘可见的焦点环。 |
模块交互与布局所有权 |
可访问性契约¶
- AR1 — 标题语义保持不变。 内置控件是同级元素,因此 h1–h6 的角色/名称不包含
#;作者编写的标题链接仍然有效。自定义标题仅接收身份标识。 - AR2 — 自定义所有权保持不变。 自定义标题仅接收身份标识,并继续负责 ID 之外的所有结构、样式和无障碍特性。
- AR3 — 渲染器扩展使用规范的显现原语。 其复制按钮保持已挂载、已命名、在无障碍树中,并在 Tab 键顺序中,同时在精细指针静止时视觉隐藏。悬停在标题行的任何位置,或将键盘焦点移入其中,都会立即显现标记。粗指针/触摸可见性、减弱动态效果和焦点保护均遵循
useContainerReveal;模块不得添加并行的媒体查询、标记、令牌或公共显现 API。
复制按钮显现扩展契约¶
渲染器扩展在内置标题行(显现所有者)上展开
useContainerReveal().getContainerProps(),并在其真正的同级 type="button" 元素上展开
getContentRevealProps({isLayoutPreserved: true})。这会生成精确的可观察状态:在精细指针静止时隐藏;
悬停标题行任意部分时可见;按钮或行内其他后代获得焦点时可见;
无需 display: none 或 visibility 即可通过键盘到达;并在该 hook 现有受支持语义下,在粗指针/触摸输入时可见。
流内控件盒的块尺寸与其相邻标题行的计算值一致,因此它永远不会提高标题行高或改变换行。
在最终视觉行末尾的一个稳定逻辑内联槽位,使标题文本、控件和相邻控件在任一方向上都互不重叠;显现以及 #/对勾的切换不会改变任何行几何或间距。
在粗指针输入时,交互和焦点几何体满足 24px AA 目标最小值,并通过 overflow-visible 内部几何体(而非流内 block-size)以该行高盒为中心。
该扩展保持不被裁剪,且不能重叠或抢占标题文本、相邻控件或前后行的输入。
指针激活不会绘制键盘焦点可见环;键盘焦点恰好绘制一个规范的、不被裁剪的 Astryx 环。
未经修改的点击、轻触、Enter 或 Space 会复制规范绝对永久链接,且绝不导航、滚动或变更当前哈希。
标题 ID 保持为传入的片段目标。成功时用 Astryx 的对勾图标替换 #,持续 1.5 秒,并通过规范的礼貌式实时区域播报一次本地化的 Link copied;失败时保持静默并保留 # 不变。
经修改/非主要指针的激活不会复制,且该按钮不暴露锚点、新标签页打开或链接上下文菜单语义。自定义标题不受此渲染器契约约束。
设计关系¶
| 状态 | 设计需求 | 呈现权威 | 模块契约 |
|---|---|---|---|
| 内置标题 | 保留语义化 h1–h6 内容,同时添加投影 ID 和同级复制控件。 | 当前源和 Markdown | FR5, FR7, FR10 |
| 复制控件 | 在标题行内对齐 #/对勾;按规范显现,且仅扩展到 24px AA 命中下限。 |
按钮和模块契约 | FR10 |
| 自定义标题 | 转发投影 ID,而不包裹或添加同级呈现。 | 调用方 | FR7 |
| No-plugin Markdown | 逐字节保留已发布的仅根级标识与嵌套标题行为。 | 当前源码与 Markdown | FR5 |
该模块不添加 Markdown 本地主题目标。按钮使用 Button 的现有目标;行属于私有布局。
父级与系统关系¶
component:Markdown拥有通用插件接缝、转换后的树、内置标题部件、默认无插件投影以及自定义渲染器替换接缝。module:Outline/parseOutlineFromMarkdown拥有仅根级条目选择,并且仅在同一插件条目被安装时才消费本模块的投影。spec:AST-036拥有不透明插件协议;本第一方模块使用该协议,但不需要特权公开能力。spec:AST-002/DEC-8允许使用此工厂,而不是宽泛的 Markdown prop;因为安装、命名空间和 URL 基址都是调用方决策,Astryx 无法推导。family:navigation-destinations拥有 URL 接受/阻止策略;本模块负责清理可选基址并复制规范 URL。
实现计划与边界¶
- 将服务端安全工厂和标识投影保留在
plugins/headingLinks.ts中;在共享的可移植插件信封内携带规范化模块配置,并仅从plugins/index.ts导出工厂和选项类型。 - 将渲染和 StyleX 保留在
plugins/下作为私有实现;Markdown 的内置标题路径仅在投影提供规范 URL 时才调用渲染器。默认路径和自定义渲染器路径保持不变。 - 将模块测试、SSR 验证、Storybook 和 Playwright 证据保留在模块中;将通用/无插件测试保留在 Markdown 中,将根级选择保留在 Outline 中。
验证映射¶
| Contract | Verification | Representative states | Failure expectation |
|---|---|---|---|
| FR1–FR4 | 模块测试、公共 API 测试、类型检查、导出/包检查 | 公共入口/选项、重复副本、无效条目/URL、h1–h6、Unicode、后缀冲突 | 导出漂移、选项丢失、错误识别、不安全 URL、不稳定 slug 或重复 ID 失败。 |
| FR5–FR7 | 模块测试以及 Markdown 和 Outline 集成测试 | 未安装/已安装插件、根级/嵌套、真实的同级按钮、自定义标题 | 默认行为改变、自定义输出被包裹、控件伪造链接语义或 ID 不一致。 |
| FR8–FR10 | SSR 测试、Storybook 和 plugins/headingLinks.a11y.chromium.spec.ts |
水合、复制/失败/计时器、不修改 location、静止/悬停/聚焦/触摸、line-height 行、24px 目标、RTL/缩放/强制颜色 | 水合恢复、反馈失真/偏移、布局扩大、目标重叠、指针绘制键盘焦点环或揭示语义漂移。 |
| Repository | 格式化、ESLint、知识/同步、i18n、Changeset 验证、核心类型检查、聚焦测试、pre-commit | 模块文件、本地化目录、Markdown/Outline 接缝、文档/spec、Storybook、工作流 | 权威过期、未翻译漂移、重复所有权、类型/lint 失败或不相关 diff 块。 |
决策日志¶
DEC-1 — 提供单个第一方插件工厂¶
Reference: module:Markdown/headingLinks/DEC-1
Decider: cixzhang, 2026-10-03
单个工厂在保留不透明插件列表的同时,只暴露安装、可选稳定命名空间和可选安全 URL 基址。其配置搭载现有可移植、带版本的插件信封,而不是创建模块的 WeakMap 或对象标识,因此重复的兼容 Core 副本会保持一致。宽泛的 Markdown prop 或单独的 Outline 选项会把同一种组合变成永久的平行 API,并可能在不同界面间漂移。
兼容的重复副本消费完全相同的信封。有效的同名通用插件如果模块数据缺失或不兼容,仍作为普通插件保留在调用方声明顺序中,但永远不会获得本模块的 ID 投影。格式错误的通用信封遵循现有消费方的容错路径,因此 Markdown 和 Outline 会保留已发布行为,而不是在渲染期间抛出。无效的直接工厂参数仍属于程序员错误。
已拒绝:模块本地选项状态;将同名相似插件提升为本模块;因包版本偏差在渲染时崩溃;默认开启行为;Markdown 布尔或命名空间 prop;单独的 Outline 标识选项;产品特定的工厂选项。
DEC-2 — 拥有单一全深度标识投影¶
Reference: module:Markdown/headingLinks/DEC-2
Decider: cixzhang, 2026-10-03
每个转换后的标题都以深度优先方式参与,因此渲染目标和根级 Outline 条目共享同一条冲突序列。NFKC Unicode slug 化和已发出 ID 预留会生成持久且可读的片段。调用方命名空间是稳定数据;运行时树位置和 useId 则不是。
已拒绝:仅限根级的插件分配;独立的 Markdown/Outline slug 生成器;纯 ASCII slug;可能导致重新输出自然数字后缀的冲突计数;运行时 ID。
DEC-3 — 渲染器扩展是一个名副其实的显露式复制按钮¶
参考: module:Markdown/headingLinks/DEC-3
决策者: cixzhang, 2026-10-03
渲染器扩展使用一个内联的尾随 # 同级元素,具有基线/逻辑间距、次要颜色和继承的排版。它的主要操作是复制,因此它是一个真正的按钮,而不是抑制导航的锚点。useContainerReveal 负责精细指针静止、标题行悬停、focus-within、粗糙/触摸和动效语义。其流内盒子与标题的 line-height 匹配,具有稳定的逻辑末尾空间和不重叠的 24px 粗糙命中区域;指针激活时不会绘制键盘焦点环。标题 ID 仍然是传入的片段目标。
已拒绝:原生片段导航;复制加导航的锚点混合体;定制的显露媒体逻辑;产品路由;新的公开显露 API。
内容边界¶
该模块仅读取转换后的标题节点,以及由已验证的插件条目携带的、用于当前文档调用的调用方提供的配置。它不会在模块局部状态中持久化文档内容、标签、目标、选项或生成的 ID。
开放问题¶
无。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx