内置项目插件¶
项目插件增加了将主项目拆分为多个独立项目的能力，可以并行构建它们，并将它们作为一个整体进行预览。这在创建多语言项目时特别有用，但也可以用于将非常大的项目拆分为更小的部分。
内置项目插件已弃用
Material for MkDocs 正在维护模式中。项目插件曾是 Insiders 版本的一部分，于 9.7.0 发布，这是包含 Insiders 版本所有功能的最后一个版本。不幸的是，项目插件被证明无法维护，并且是创建 Zensical 的主要动机之一。
如果您考虑使用项目插件，请注意已知问题将 不会 被修复。
目标¶
工作原理¶
该插件扫描配置的 projects 目录 中的 mkdocs.yml 文件，识别所有嵌套项目并并行构建它们。如果未另行配置，插件期望您的项目具有以下目录结构，例如多语言项目：
.
├─ docs/
├─ projects/
│ ├─ en/
│ │ ├─ docs/
│ │ └─ mkdocs.yml
│ └─ de/
│ ├─ docs/
│ └─ mkdocs.yml
└─ mkdocs.yml
该插件最有用和有趣的功能之一是它允许从主项目 预览您的网站，同时仍然能够单独预览和构建每个项目。这对于多语言项目尤其有用。
如果在 预览您的网站 时，您更改了其中一个项目中的文件，插件只会重新构建该项目，并确保 MkDocs 也会重新加载相关文件。这也为将主项目拆分为多个项目以获得更好的编辑体验提供了机会。
存在一些 限制，但我们正在努力消除它们。
何时使用¶
该插件的出现是因为我们需要一种方便且可扩展的方法来构建我们的 examples 存储库，该存储库包含许多自包含且可运行的项目，用户可以下载并用作启动新项目或 创建重现 的基础。
当您想创建一个多语言项目，或者有一个非常大的现有项目时，您可能会考虑使用该插件，因为它使管理、编辑和构建更加舒适。
配置¶
要开始使用项目插件，只需将以下行添加到 mkdocs.yml 中，并将主项目拆分为多个可以并行构建的独立项目：
项目插件内置于 Material for MkDocs 中，无需安装。
一般设置¶
以下设置可用：
enabled¶
9.7.0 true
使用此设置在 构建您的项目 时启用或禁用插件。如果您想禁用插件，例如用于本地构建，可以在 mkdocs.yml 中使用 环境变量：
此配置仅在持续集成（CI）期间启用插件。
concurrency¶
9.7.0 可用 CPU - 1
在可用 CPU 更多的情况下，插件可以并行处理更多工作，从而更快地构建项目。如果您想完全禁用并发处理，请使用：
默认情况下，插件使用所有可用 CPU - 1，最低为 1。
缓存¶
该插件实现了 智能缓存 机制，确保仅在项目内容更改时才重新构建项目。虽然初始构建可能需要一些时间，但使用缓存是个好主意，因为它将加速后续构建。
以下设置可用于缓存：
cache¶
9.7.0 true
使用此设置指示插件绕过缓存，以便重新构建所有项目，即使缓存可能没有过期。通常情况下，除非在调试插件本身时，不需要指定此设置。可以通过以下方式禁用缓存：
cache_dir¶
9.7.0 .cache/plugin/projects
通常情况下，不需要指定此设置，除非您想更改根目录中缓存元数据的路径。如果您想更改它，请使用：
日志记录¶
以下设置可用于日志记录：
log¶
9.7.0 true
使用此设置控制插件在构建您的网站时是否应显示项目的日志消息。虽然不推荐，但您可以通过以下方式禁用日志记录：
log_level¶
9.7.0 info
使用此设置控制插件在遇到错误时应采用的日志级别，这要求 log 设置已启用。可用的日志级别如下：
报告错误和警告，在 strict 模式下终止构建。
项目¶
以下设置可用于项目：
projects¶
9.7.0 true
使用此设置启用或禁用项目的构建。目前，插件的唯一目的是构建项目，因此它等同于 enabled 设置，但将来可能会添加其他功能。如果您想禁用项目的构建，请使用：
projects_dir¶
9.7.0 projects
使用此设置更改项目所在的文件夹。通常不需要更改此设置，但如果您想重命名文件夹或更改其文件系统位置，请使用：
请注意，projects 目录 仅用于项目组织 – 它不包含在项目 URL 中，因为项目会被插件自动提升。
提供的路径是从根目录解析的。
projects_config_files¶
9.7.0 */mkdocs.yml
使用此设置更改插件在扫描 projects 目录 时查找的配置文件的位置或名称。当配置文件位于项目的子目录中时，例如 docs/mkdocs.yml，调整此设置可能是必要的：
-
如果所有项目共享相同的配置文件位置，例如
docs/mkdocs.yml，建议完全限定路径，因为解析速度比**通配符模式更快。此配置适用于以下目录结构，这在使用 git 子模块的项目中相当常见：
提供的路径是从 projects 目录 解析的。
projects_config_transform¶
使用此设置在构建之前转换从 mkdocs.yml 读取的每个项目的配置，这允许在一起构建它们时调整每个项目的配置，但在单独构建时保持不变：
提供的模块和函数名称在 Python 的 模块搜索路径 中查找。您需要在构建网站时将根目录添加到搜索路径，以便 Python 可以解析它。最简单的方法是将工作目录添加到 PYTHONPATH 环境变量：
如何定义配置转换函数
python/name 标签由 PyYAML 提供，必须指向 Python 的 模块搜索路径 中的有效模块和函数名称。插件将 project 和顶级 config 对象传递给该函数。
作为示例，我们可以从顶级配置中继承所有项目的 use_directory_urls 设置：
提升¶
以下设置可用于提升：
hoisting¶
9.7.0 true
使用此设置启用或禁用将主题文件提升到主项目。如果您禁用此设置，每个项目将获得主题文件的副本，这可以被视为冗余：
通常建议启用提升，因为它可以加快部署速度和项目网站的加载速度，因为所有项目的文件都是相同的，可以去重。
限制¶
该插件是 Material for MkDocs 的最新添加之一，这意味着它相对年轻并且存在一些限制。我们正在努力消除这些限制，并乐于接收反馈并了解您在 #5800 中的需求。当前的限制包括：
-
仅基本的多语言支持: 我们将调查如何为多语言项目提供更好的支持，以便更容易地相互链接项目并在它们之间切换。
-
单独的搜索索引和网站地图: 目前，项目是完全独立的，这意味着它们将拥有单独的搜索索引和网站地图。