页面结构
在整个 MDN 中,都使用文档结构来提供 MDN 文章中信息的一致呈现。此页面列出了描述这些结构的文章,以便您可以适当地修改您编写、编辑或翻译的文档的页面内容。
- 横幅和通知
横幅和通知显示在某些页面上,特别是 API 参考中,以便突出显示会影响所描述内容使用方式的重要因素。例如,横幅用于突出显示特定接口、方法或属性何时已弃用,不应在生产代码中使用,或者只能在安全上下文中使用。
- 代码示例
在 MDN 上,您会看到许多代码示例插入到页面中,以演示 Web 平台功能的使用方法。本文讨论了用于向页面添加代码示例的不同机制,以及何时应该使用哪些机制。
- 兼容性表格和浏览器兼容性数据存储库 (BCD)
MDN 采用标准格式的表格来说明所有浏览器(如 DOM、HTML、CSS、JavaScript、SVG 等)中共享技术的兼容性。为了以编程方式在多个项目中提供此数据,从浏览器兼容性数据存储库构建了一个 Node.js 包,并发布到 npm。
- 功能状态
功能状态向开发者提供有关浏览器供应商之间功能实施阶段的信息,并且是以下之一:
- 链接宏
MDN 提供了许多宏来创建始终指向 MDN 内容的最新链接。在本指南中,您将了解可以使用哪些 MDN 交叉引用宏来包含指向另一页面的单个链接或指向文档所有子页面的链接列表。
- 实时示例
MDN 支持在文章中显示代码块作为实时示例,使读者能够看到代码及其输出在网页上的显示效果。此功能使读者能够准确了解执行的代码将产生什么结果,从而使文档更具动态性和指导性。它还允许作者完全确定文档中的代码块是否具有预期的输出,并在与不同浏览器一起使用时正常工作。
- 页面类型
MDN 上重复使用多种类型的页面。本文介绍了这些页面类型、其用途,并提供了每个页面的示例以及创建新页面时使用的模板。
- 侧边栏
MDN 社区成员可以编辑的所有页面都包含一个侧边栏。这些侧边栏是使用宏创建的。本文介绍了不同的 MDN 侧边栏宏,演示了如何在 MDN 页面上包含侧边栏。
- 规范表格
MDN 上的每个参考页面都应提供有关定义该 API 或技术规范或规范的信息。本文演示了这些表格的外观,并说明了如何添加它们。
- 语法部分
MDN 参考页面的语法部分包含一个语法框,定义了功能的确切语法(例如,它可以接受哪些参数,哪些参数是可选的?)。本文说明了如何为参考文章编写语法框。
- 使用宏
MDN 运行所在的Yari 平台提供了一个宏系统,KumaScript,它可以自动化某些任务。本文提供了有关如何在文章中调用 MDN 宏的信息。