理念

在选择 Material for MkDocs 之前，了解该项目的理念是一个好主意，以确保它与您的目标相一致。本页面解释了 Material for MkDocs 的设计原则，并讨论了本文档中使用的约定惯例。

设计原则

• 只需使用 Markdown：专注于文档内容，在几分钟内创建一个专业的静态网站。无需了解 HTML、CSS 或 JavaScript - 让 Material for MkDocs 为您处理繁重的工作。

• 适用于所有设备：自信地提供您的文档 - 底层布局会自动适应可用屏幕空间，无论查看设备的类型或大小如何。

• 量身定制：通过几行配置更改颜色、字体、语言、图标、标志等等。Material for MkDocs 可以轻松扩展，并提供大量选项来改变外观和行为。

• 快速轻巧：不要让用户等待 - 使用其中一个最快的主题，以小的占用空间获得令人难以置信的价值，具有出色的性能，获得良好的搜索引擎排名，并使用户满意并返回。

• 可访问性：将可访问性作为优先事项 - 用户可以使用触摸设备、键盘和屏幕阅读器浏览您的文档。语义化标记确保您的文档适用于所有人。

• 开源：相信 20,000 多个用户 - 选择一个成熟且资金充足的解决方案，使用最先进的开源技术构建。拥有您的内容所有权，不必担心供应商锁定。采用 MIT 许可证。

约定惯例

符号

本文档使用一些符号进行说明。在继续阅读之前，请确保您熟悉以下约定惯例的列表：

  内部测试版

一些功能目前仅作为 Material for MkDocs 的内部测试版的一部分而不是社区版提供。请查阅内部测试版指南以了解如何获取访问权限。

  {x.x.x}

标签图标与版本号结合使用，表示特定功能或行为的添加时间。如果要使用该功能，请确保至少使用此版本。

  {file.ext}

源文件图标与文件名有时在跨多个文件的代码示例中使用。文件名（或路径）始终从mkdocs.yml的位置开始。

  默认值：value

mkdocs.yml中的某些属性具有默认值，当作者没有明确定义它们时使用。属性的默认值始终包含在内。

  功能标志

大多数功能都隐藏在功能标志后面，这意味着必须通过mkdocs.yml显式启用它们。这允许存在可能正交的功能。

  实验性的

一些较新的功能仍被视为实验性的，这意味着它们可能（尽管很少）随时发生更改，包括完全删除（尚未发生）。

  插件

一些功能是通过 MkDocs 出色的插件架构实现的，其中一些是内置的，并随 Material for MkDocs 一起分发，无需安装。

  实用工具

除了插件之外，还有一些实用工具构建在 MkDocs 之上，以提供扩展功能，例如版本控制的支持。