按网站规则编写能正常构建的 MDX 文档页面

## 动笔前先了解文档网站的结构 将存储库视为模式驱动的文档应用程序，而不是松散的 Markdown 文件集合。 确定站点生成器、文档主题、组件框架、包管理器、运行时版本和部署目标。 使用存储库锁定的可复现命令安装依赖项。 使运行时和包管理器版本与存储库元数据保持一致。 确认主要贡献分支，而不是假定它采用惯用名称。 区分面向用户的页面、可复用的局部内容、变更日志、术语表数据、产品元数据和其他结构化集合。 将自定义组件、内容模式、Markdown 插件、代码高亮插件、图标、资产、样式和动态路由保留在各自指定的层中。 以不同方式处理静态公共文件与由站点生成器处理的图像。 将中央组件导出模块用作 MDX 的公共导入界面。 以集合模式作为可接受字段和值类型的权威依据。 将生成的技能或参考目录视为构建产物。 不得编辑生成目录，也不得提交已忽略的生成内容。 更改专用审查机器人或部署工作进程之前，应阅读嵌套的说明。 将存储库特定的样式、组件和流程参考资料用作权威指南。 不得让通用 Markdown 习惯凌驾于站点的 MDX 和模式规则之上。 ## 把页面放进正确的文件夹，并按规则命名文件 将面向用户的文档页面放在产品或主题目录下。 将可复用的片段放在局部内容集合中。 将变更日志条目放在对应的产品或主题子目录中。 将术语表词条和其他结构化元数据放在由各自模式管理的集合中。 当站点有此要求时，每个可导航的内容文件夹中都必须有索引页面。 使用全小写文件名，并用连字符分隔单词。 将内容目录限制为明确允许的文本和数据扩展名。 通常允许的类型是 MDX、JSON、YAML 和纯文本。 让扩展名验证实施允许列表，而不是隐藏不受支持的文件。 不得将图像或任意二进制文件放入由模式扫描的内容目录。 将可处理的图像放入专用资产树以供优化。 只有在确实必须原样提供静态文件时，才将其放入公共树。 使目录名称与现有产品元数据保持一致。 不得为未知的产品键创建变更日志或集合子目录。 应保留既有集合边界，而不是另造一个平行的内容位置。 移动页面时，应更新指向该页面的链接、导航元数据、重定向和相关局部内容引用。 ## 按网站要求填写页面设置（前置元数据） 为每个文档页面提供满足其集合模式的前置元数据块。 提供简洁的页面标题。 只要所选内容类型有此要求，就提供搜索说明。 从存储库允许的枚举中选择页面类型。 常见类型包括 `concept`、`configuration`、`example`、`FAQ`、`getting started`、`how-to`、`integration`、`implementation`、`overview`、`reference`、`release notes`、`solution`、`troubleshooting` 和 `tutorial`。 当模式提供时，使用 `design guide`、`learning unit`、`navigation`、`reference architecture` 和 `video` 等专用类型。 只有在需要明确排序时才使用侧边栏顺序。 只有在导航文本应与页面标题不同时才使用侧边栏标签。 通过现有元数据键引用产品或主题。 教程内容应使用文档规定的难度枚举。 用规定的年-月-日格式记录审查日期。 不得臆造模式字段或枚举值。 确保 YAML 缩进和列表结构有效。 更改集合定义或模式后，重新生成内容集合类型。 根据相应模式验证数据文件，而不是依赖目视检查。 当页面的目的、产品、标题或审查状态发生变化时，应同步页面元数据。 ## 编写不会出现语法错误、能正常构建的 MDX 页面 遵循存储库的权威写作与格式指南。 将 MDX 视为 Markdown 加上嵌入式组件语言，其解析规则更加严格。 当花括号和尖括号字符用于普通文本时，应对其进行转义或使用代码格式。 请记住，即使在普通文本中，MDX 也会将这些字符解释为表达式或组件。 导入页面所使用的每个组件。 将导入语句放在前置元数据之后、页面内容之前。 只使用受支持的语法高亮语言标识符。 使用存储库的纯文本语言标识符编写通用终端输出。 代码围栏中的语言标识符应使用小写。 内部站点链接应使用相对于根目录的绝对路径。 不得对内部目标使用完整的生产环境 URL。 不得使用不受支持的相对页面链接。 保持标题层级连续，不得跨越层级。 可复制的命令中应省略 shell 提示符。 编写简洁的步骤，确保操作、位置和预期结果都没有歧义。 当多个页面需要同一份持续维护的文本时，将可复用的说明放在局部内容中。 根据文档所述的 API 和当前产品行为验证代码示例。 ## 按规则使用组件和图片，只在需要时修改重定向 只能通过存储库的中央组件统一导出模块导入 MDX 组件。 查阅组件文档，了解必需的属性和使用限制。 如果已有受支持的公共组件，不得将组件内部实现复制到内容中。 将新组件代码放在指定的组件目录。 使用规定的自定义元素前缀和短横线命名约定。 将每个组件保存在以该组件命名的目录中。 使用带规定后缀的 PascalCase 类名。 不得仅为应用较新的前缀规则而重命名获得豁免的旧版元素。 将源图像保存在对应产品或主题的优化资产目录中。 通过本地完整构建验证图像路径。 只有在页面移动或 URL 迁移有此需要时才修改重定向。 重定向源路径应以规定的斜杠、可接受的文件后缀或通配符后缀结尾。 不得在重定向源 URL 中放置片段。 审查前检测重定向循环。 每当重定向文件发生变化时，都要运行专用重定向验证器。 将组件、图像、链接和重定向更改限制在页面的预期范围内。 ## 在本地和 CI 中通过所需检查后再说页面已完成 每次更改内容后，都要运行模式检查和类型检查。 使用本地完整构建验证 MDX 解析、图像路径和内部链接。 在本地完整验证构建期间启用内部链接检查。 不得在资源受限的 CI 中运行已知会超时的完整构建。 在 CI 中运行类型检查、代码检查和格式检查，将其作为精简的安全检查集。 更改代码时，还要运行存储库的完整测试套件。 提交前格式化每个已编辑文件。 自动修复后，运行存储库的格式检查。 只有在重定向配置发生变化时才运行重定向验证。 更改模式或集合后，运行集合类型同步。 在可行时，使本地完整验证顺序与 CI 流水线保持一致。 应预期 CI 检查文件扩展名、类型、代码质量、格式、构建与链接、重定向和测试。 即使样式扫描器警告并非硬性失败，也要将其作为审查证据。 只要缺少直接相关的验证门禁，就不得报告页面已准备就绪。 区分 CI 环境限制与实际内容故障。 每次修正性编辑后，重新运行直接受影响的检查。 ## 用网站的工具为每个目录条目生成 ID 并保持不变 在规定的首行位置，为每个目录条目数据文件提供唯一且稳定的标识符。 使用存储库规定的精确标识符长度和减少混淆的字符集。 对于六字符方案，应验证每个生成值都恰好包含六个字符。 当方案要求时，排除外观容易混淆的字符。 随机生成标识符，不得根据名称推导。 不得手工编造、猜测或复制标识符。 使用存储库的标识符工具检查整个集合。 对于缺失、格式错误或重复的标识符，使用该工具的修复模式。 显示名称或文件名发生变化时，应保留现有的有效标识符。 只有在修复已确认的验证错误时，才能更改现有标识符。 始终一致地使用唯一一种规定的 YAML 扩展名。 将标识符生成视为自动化操作，而不是编辑选择。 检查整个目录集合中的唯一性。 在 CI 中保留标识符生成和模式验证。 提交生成的更改之前，审查该工具的 diff。 工具成功后，不得手动调整生成的标识符。 ## 提交修改时遵守各项任务的说明和提交规则 在编写、编辑、审查示例、添加变更日志或准备拉取请求之前，使用存储库的贡献路由器。 遵循该路由器选择的任务特定参考资料。 更改专业机器人的代码、工作流路由、状态或部署之前，应阅读其本地说明。 使工具特定的符号链接始终指向已提交的共享代理配置。 只有当存储库技能的说明与任务匹配时才加载它。 使用权威样式指南决定措辞和格式。 使用组件目录查找属性、示例和必需模式。 使用流程指南编写分步说明。 在代码更改影响的每个运行时工作区中运行测试。 区分工作进程、服务器运行时和站点生成器的测试。 按照存储库接受的产品前缀或类型前缀格式编写提交。 使提交说明具体对应用户可见的修正或技术修正。 不得包含无关的格式更改、生成内容或产品更改。 只有当内容、模式、导入、资产、链接、重定向、测试和贡献约定相互一致时才批准。