内置项目插件¶

¥Built-in projects plugin¶

项目插件新增了将主项目拆分为多个独立项目的功能，这些项目可以同时构建并作为一个项目进行预览。此功能在创建多语言项目时尤其有用，也可用于将大型项目拆分为多个较小的项目。

¥The projects plugin adds the ability to split your main project into multiple distinct projects, build them concurrently and preview them together as one. This is particularly useful when creating a multi-language project, but can also be used to split very large projects into smaller parts.

仅限赞助商– 此插件目前仅供我们出色的赞助商使用。

¥ Sponsors only – this plugin is currently reserved to our awesome sponsors.

客观的¶

¥Objective¶

工作原理¶

¥How it works¶

该插件会扫描已配置的项目目录中的mkdocs.yml文件，识别所有嵌套项目并同时构建它们。如果没有其他配置，则该插件要求你的项目具有以下目录布局，例如，对于多语言项目：

¥The plugin scans the configured projects directory for mkdocs.yml files, identifies all nested projects and builds them concurrently. If not configured otherwise, the plugin expects that your project has the following directory layout, e.g. for a multi-language project:

.
├─ docs/
├─ projects/
│  ├─ en/
│  │  ├─ docs/
│  │  └─ mkdocs.yml
│  └─ de/
│     ├─ docs/
│     └─ mkdocs.yml
└─ mkdocs.yml

该插件最实用、最有趣的功能之一是，它允许在主项目中预览你的网站，同时仍然可以单独预览和构建每个项目。这对于多语言项目尤其有用。

¥One of the most useful and interesting features of the plugin is that it allows previewing your site from the main project, while still being able to preview and build each project individually. This is especially useful for multi-language projects.

如果您在预览网站时更改了某个项目中的文件，该插件只会重建该项目，并确保 MkDocs 也会重新加载相关文件。这也为将主项目拆分为多个项目创造了机会，以获得更好的编辑体验。

¥If, when previewing your site, you change a file in one of the projects, the plugin only rebuilds this project and makes sure that MkDocs will also reload the associated files. This also creates the opportunity for splitting your main project into several projects for a better editing experience.

存在一些限制，但我们正在努力消除它们。

¥There are some limitations, but we're working hard to remove them.

何时使用¶

¥When to use it¶

该插件的出现是因为我们需要一种方便且可扩展的方法来构建我们的示例存储库，该存储库具有许多独立且可运行的项目，用户可以在引导新项目或创建复制品时下载并用作基础。

¥The plugin came into existence because we needed a convenient and scalable method to build our examples repository, which features many self-contained and runnable projects that users can download and use as a basis when bootstrapping a new project or creating a reproduction.

当您想要创建一个多语言项目，或者有一个非常大的现有项目时，您可能会考虑使用该插件，因为它使管理、编辑和构建更加舒适。

¥When you want to create a multi-language project, or have a very large existing project, you might consider using the plugin, as it makes managing, editing and building more comfortable.

配置¶

¥Configuration¶

insiders-4.38.0项目 – 内置

¥ insiders-4.38.0 projects – built-in

为了开始使用项目插件，只需将以下几行添加到mkdocs.yml ，并将主项目拆分为几个可以同时构建的不同项目：

¥In order to get started with the projects plugin, just add the following lines to mkdocs.yml, and split your main project into several distinct projects that can be built concurrently:

plugins:
  - projects

项目插件内置于 MkDocs 的 Material 中，无需安装。

¥The projects plugin is built into Material for MkDocs and doesn't need to be installed.

一般的¶

¥General¶

可用的设置如下：

¥The following settings are available:

`enabled`¶

¥enabled¶

insiders-4.38.0真实

¥ insiders-4.38.0 true

使用此设置在构建项目时启用或禁用插件。如果要禁用该插件（例如，对于本地构建），可以在mkdocs.yml中使用环境变量：

¥Use this setting to enable or disable the plugin when building your project. If you want to disable the plugin, e.g., for local builds, you can use an environment variable in mkdocs.yml:

plugins:
  - projects:
      enabled: !ENV [CI, false]

此配置仅在持续集成（CI）期间启用插件。

¥This configuration enables the plugin only during continuous integration (CI).

`concurrency`¶

¥concurrency¶

insiders-4.38.0可用 CPU - 1

¥ insiders-4.38.0 available CPUs - 1

有了更多可用的 CPU，插件可以并行执行更多工作，从而更快地构建项目。如果您想完全禁用并发处理，请使用：

¥With more CPUs available, the plugin can do more work in parallel, and thus build projects faster. If you want to disable concurrent processing completely, use:

plugins:
  - projects:
      concurrency: 1

默认情况下，该插件使用所有可用的 CPU - 1，最少 1 个。

¥By default, the plugin uses all available CPUs - 1 with a minimum of 1.

缓存¶

¥Caching¶

该插件实现了智能缓存机制，确保项目仅在内容发生变化时才重新构建。虽然初始构建可能需要一些时间，但使用缓存是个好主意，因为它可以加快后续构建的速度。

¥The plugin implements an intelligent caching mechanism, ensuring that a project is only rebuilt when its contents change. While the initial build might take some time, it's a good idea to use caching, as it will speed up consecutive builds.

以下设置可用于缓存：

¥The following settings are available for caching:

`cache`¶

¥cache¶

insiders-4.38.0真实

¥ insiders-4.38.0 true

使用此设置可指示插件绕过缓存，以便重建所有项目，即使缓存可能没有过期。通常无需指定此设置，除非调试插件本身。可以使用以下命令禁用缓存：

¥Use this setting to instruct the plugin to bypass the cache, in order to rebuild all projects, even though the cache may not be stale. It's normally not necessary to specify this setting, except for when debugging the plugin itself. Caching can be disabled with:

plugins:
  - projects:
      cache: false

`cache_dir`¶

¥cache_dir¶

insiders-4.38.0 .cache/插件/项目

¥ insiders-4.38.0 .cache/plugin/projects

通常不需要指定此设置，除非您想要更改根目录中缓存元数据的路径。如果您要更改它，请使用：

¥It is normally not necessary to specify this setting, except for when you want to change the path within your root directory where the metadata is cached. If you want to change it, use:

plugins:
  - projects:
      cache_dir: my/custom/dir

日志记录¶

¥Logging¶

以下设置可用于日志记录：

¥The following settings are available for logging:

`log`¶

¥log¶

insiders-4.47.0真实

¥ insiders-4.47.0 true

使用此设置可控制插件在构建网站时是否显示来自项目的日志消息。虽然不建议这样做，但您可以使用以下方式禁用日志记录：

¥Use this setting to control whether the plugin should display log messages from projects when building your site. While not being recommended, you can disable logging with:

plugins:
  - projects:
      log: false

`log_level`¶

¥log_level¶

insiders-4.47.0信息

¥ insiders-4.47.0 info

使用此设置可控制插件在遇到错误时应使用的日志级别，这需要启用日志设置。可用的日志级别如下：

¥Use this setting to control the log level that the plugin should employ when encountering errors, which requires that the log setting is enabled. The following log levels are available:

errorwarninfodebug

plugins:
  - projects:
      log_level: error

仅报告错误。

¥Only errors are reported.

plugins:
  - projects:
      log_level: warn

报告错误和警告，以严格模式终止构建。

¥Errors and warnings are reported, terminating the build in strict mode.

plugins:
  - projects:
      log_level: info

报告错误、警告和信息消息。

¥Errors, warnings and informational messages are reported.

plugins:
  - projects:
      log_level: debug

报告所有消息，包括调试消息。

¥All messages are reported, including debug messages.

项目¶

¥Projects¶

以下设置可用于项目：

¥The following settings are available for projects:

`projects`¶

¥projects¶

insiders-4.38.0真实

¥ insiders-4.38.0 true

使用此设置可启用或禁用项目构建。目前，该插件的唯一用途是构建项目，因此它相当于启用的设置，但未来可能会添加其他功能。如果您想禁用项目构建，请使用：

¥Use this setting to enable or disable building of projects. Currently, the plugin's sole purpose is to build projects, so it's equivalent to the enabled setting, but in the future, other features might be added. If you want to disable building of projects, use:

plugins:
  - projects:
      projects: false

`projects_dir`¶

¥projects_dir¶

insiders-4.38.0项目

¥ insiders-4.38.0 projects

使用此设置可更改项目所在的文件夹。通常无需更改此设置，但如果您想重命名文件夹或更改其文件系统位置，请使用：

¥Use this setting to change the folder where your projects are located. It's normally not necessary to change this setting, but if you want to rename the folder or change its file system location, use:

plugins:
  - projects:
      projects_dir: projects

请注意，项目目录仅用于项目组织 - 它不包含在项目 URL 中，因为项目是由插件自动提升的。

¥Note that the projects directory is solely used for project organization – it is not included in project URLs, since projects are automatically hoisted by the plugin.

提供的路径是从根目录解析的。

¥The provided path is resolved from the root directory.

`projects_config_files`¶

¥projects_config_files¶

insiders-4.42.0 */mkdocs.yml

¥ insiders-4.42.0 */mkdocs.yml

使用此设置可以更改插件在扫描项目目录时查找的配置文件的位置或名称。当配置文件位于项目子目录中时，可能需要调整此设置，例如docs/mkdocs.yml ：

¥Use this setting to change the location or name of configuration files the plugin will look for when scanning the projects directory. Adjusting this setting can be necessary when the configuration files are located in subdirectories of projects, e.g. docs/mkdocs.yml:

plugins:
  - projects:
      projects_config_files: "**/mkdocs.yml" # (1)!

如果所有项目的配置文件都共享相同的位置，例如docs/mkdocs.yml ，则建议完全限定路径，因为它比** glob 模式解析得更快。
```
plugins:
  - projects:
      projects_config_files: "*/docs/mkdocs.yml"
```
```
plugins:
  - projects:
      projects_config_files: "*/docs/mkdocs.yml"
```
plugins: - projects: projects_config_files: "*/docs/mkdocs.yml"插件： - 项目： projects_config_files：“*/docs/mkdocs.yml”此配置适合以下目录结构，这对于使用 git 子模块的项目来说很常见：
```
.
├─ docs/
├─ projects/
│  ├─ git-submodule-a/
│  │  └─ docs/
│  │     └─ mkdocs.yml
│  └─ git-submodule-b/
│     └─ docs/
│        └─ mkdocs.yml
└─ mkdocs.yml
```
```
.
├─ docs/
├─ projects/
│  ├─ git-submodule-a/
│  │  └─ docs/
│  │     └─ mkdocs.yml
│  └─ git-submodule-b/
│     └─ docs/
│        └─ mkdocs.yml
└─ mkdocs.yml
```
. ├─ docs/ ├─ projects/ │ ├─ git-submodule-a/ │ │ └─ docs/ │ │ └─ mkdocs.yml │ └─ git-submodule-b/ │ └─ docs/ │ └─ mkdocs.yml └─ mkdocs.yml . │ │ │ └─ docs/ │ │ └─ mkdocs.yml │ └─ git-submodule-b/ │ └─ docs/ │ └─ mkdocs.yml └─ mkdocs.yml

提供的路径是从项目目录中解析的。

¥If all projects share the same location for their configuration files, e.g., docs/mkdocs.yml, it's advisable to fully qualify the path, as it's faster to resolve than a ** glob pattern.

`projects_config_transform`¶

¥projects_config_transform¶

insiders-4.42.0

¥This configuration fits the following directory structure, which is quite common for projects using git submodules:

使用此设置在构建之前转换从mkdocs.yml读取的每个项目的配置，这允许在一起构建每个项目时调整每个项目的配置，但在单独构建它们时保持不变：

¥The provided path is resolved from the projects directory.

plugins:
  - projects:
      projects_config_transform: !!python/name:projects.transform

提供的模块和函数名称会在 Python 的模块搜索路径中查找。构建站点时，您需要将根目录添加到搜索路径中，以便 Python 能够解析它。最简单的方法是将工作目录添加到PYTHONPATH环境变量中：

¥ insiders-4.42.0

export PYTHONPATH=.

如何定义配置转换函数

¥Use this setting to transform the configuration of each project as read from mkdocs.yml before it is built, which allows for adjusting the configuration of each project when building them together, but leave them untouched when building them individually:

python/name标签由PyYAML提供，必须指向 Python模块搜索路径中有效的模块和函数名称。插件将project和顶级config对象传递给函数。

¥The provided module and function name are looked up in Python's module search path. You need to add your root directory to the search path when building your site, so Python can resolve it. The easiest way is to add the working directory to the PYTHONPATH environment variable:

例如，我们可以从顶级配置中继承所有项目的use_directory_urls设置：

¥How to define a configuration transformation function

projects/__init__.py

from mkdocs.config.defaults import MkDocsConfig

# Transform project configuration
def transform(project: MkDocsConfig, config: MkDocsConfig):
    project.use_directory_urls = config.use_directory_urls

提升¶

¥Hoisting¶

下列设置可用于吊装：

¥The python/name tag is provided by PyYAML and must point to a valid module and function name within Python's module search path. The plugin passes the project and top-level config objects to the function.

`hoisting`¶

¥hoisting¶

insiders-4.39.0真实

¥As an example, we can inherit the use_directory_urls setting for all projects from the top-level configuration:

使用此设置可以启用或禁用将主题文件提升到主项目的功能。如果禁用此设置，则每个项目都会收到主题文件的副本，这些副本可视为冗余：

¥The following settings are available for hoisting:

plugins:
  - projects:
      hoisting: false

通常建议启用提升，因为它可以更快地部署并更快地加载项目站点，因为所有项目的文件都是相同的并且可以进行重复数据删除。

¥ insiders-4.39.0 true

限制¶

¥Limitations¶

该插件是 Material for MkDocs 的最新功能之一，这意味着它还比较年轻，并且存在一些限制。我们正在努力消除这些限制，并乐意在#5800中收到反馈并了解您的需求。当前的限制如下：

¥Use this setting to enable or disable hoisting of themes files to the main project. If you disable this setting, each project receives a copy of the theme's files, which can be considered redundant:

仅提供基本的多语言支持：我们将研究如何为多语言项目提供更好的支持，以便更轻松地互连项目并在它们之间切换。
单独的搜索索引和站点地图：目前，这些项目完全独立，这意味着它们将有单独的搜索索引和站点地图。