diff --git a/CHANGELOG b/CHANGELOG
index b46867aa5..0ca98300b 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -1,3 +1,11 @@
+mkdocs-material-9.3.2+insiders-4.42.0 (2023-09-19)
+
+ * Added support for using git submodules in projects plugin
+ * Added support for transforming project configurations
+ * Improved resilience of optimize and blog plugin
+ * Fixed optimize plugin crashing on .jpeg extension
+ * Fixed project URLs not using site URLs in projects plugin
+
mkdocs-material-9.3.2 (2023-09-19)
* Updated Slovenian translations
diff --git a/docs/insiders/changelog.md b/docs/insiders/changelog.md
index 880b93895..a7d53c2ca 100644
--- a/docs/insiders/changelog.md
+++ b/docs/insiders/changelog.md
@@ -2,6 +2,14 @@
## Material for MkDocs Insiders
+### 4.42.0 September 19, 2023 { id="4.42.0" }
+
+- Added support for using git submodules in projects plugin
+- Added support for transforming project configurations
+- Improved resilience of optimize and blog plugin
+- Fixed optimize plugin crashing on `.jpeg` extension
+- Fixed project URLs not using site URLs in projects plugin
+
### 4.41.0 September 11, 2023 { id="4.41.0" }
- Improved multi-instance support for optimize plugin
@@ -480,7 +488,7 @@
### 4.12.0 March 27, 2022 { id="4.12.0" }
- Added support for card grids and grid layouts
-- Fixed #3685: Annotations sometimes broken when using instant loading
+- Fixed #3685: Annotations sometimes broken when using instant loading
- Fixed #3742: Automatically add Mermaid.js when building for offline usage
### 4.11.0 March 6, 2022 { id="4.11.0" }
diff --git a/docs/plugins/meta.md b/docs/plugins/meta.md
index c754e0010..3c4f72669 100644
--- a/docs/plugins/meta.md
+++ b/docs/plugins/meta.md
@@ -181,9 +181,9 @@ The following settings are available for meta files:
-Use this setting to change the file the plugin will look for when scanning
-the [`docs` directory][mkdocs.docs_dir]. It's normally not necessary to change
-this setting, but if you want to change it, use:
+Use this setting to change the meta file name the plugin will look for when
+scanning the [`docs` directory][mkdocs.docs_dir]. It's normally not necessary to
+change this setting, but if you want to change it, use:
``` yaml
plugins:
diff --git a/docs/plugins/offline.md b/docs/plugins/offline.md
index 6e6b72452..760c01b90 100644
--- a/docs/plugins/offline.md
+++ b/docs/plugins/offline.md
@@ -34,9 +34,9 @@ interactivity of your project. The offline plugin makes sure that site search
keeps working by moving the search index to a JavaScript file, and leveraging
@squidfunk's [iframe-worker] shim.
-Additionally, the plugin automatically disables the
-[`use_directory_urls`][mkdocs.use_directory_urls] setting, ensuring that users
-can open your documentation directly from the local file system.
+Additionally, the plugin automatically disables the [`use_directory_urls`]
+[mkdocs.use_directory_urls] setting, ensuring that users can open your
+documentation directly from the local file system.
There are some [limitations].
diff --git a/docs/plugins/projects.md b/docs/plugins/projects.md
index b308762f1..e989e7d7d 100644
--- a/docs/plugins/projects.md
+++ b/docs/plugins/projects.md
@@ -223,6 +223,107 @@ automatically hoisted by the plugin.
The provided path is resolved from the root directory.
+---
+
+####
+
+
+
+
+
+Use this setting to change the location or name of configuration files the
+plugin will look for when scanning the [`projects` directory]
+[config.projects_dir]. Adjusting this setting can be necessary when the
+configuration files are located in subdirectories of projects, e.g.
+`docs/mkdocs.yml`:
+
+``` yaml
+plugins:
+ - projects:
+ projects_config_files: "**/mkdocs.yml" # (1)!
+```
+
+1. 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.
+
+ ``` yaml
+ plugins:
+ - projects:
+ projects_config_files: "*/docs/mkdocs.yml"
+ ```
+
+ This configuration fits the following directory structure, which is quite
+ common for projects using git submodules:
+
+ ``` { .sh .no-copy }
+ .
+ ├─ docs/
+ ├─ projects/
+ │ ├─ git-submodule-a/
+ │ │ └─ docs/
+ │ │ └─ mkdocs.yml
+ │ └─ git-submodule-b/
+ │ └─ docs/
+ │ └─ mkdocs.yml
+ └─ mkdocs.yml
+ ```
+
+The provided path is resolved from the [`projects` directory]
+[config.projects_dir].
+
+---
+
+####
+
+
+
+
+
+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:
+
+``` yaml
+plugins:
+ - projects:
+ projects_config_transform: !!python/name:projects.transform
+```
+
+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`][PYTHONPATH] environment variable:
+
+``` .sh
+export PYTHONPATH=.
+```
+
+!!! tip "How to define a configuration transformation function"
+
+ The [`python/name`][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.
+
+ As an example, we can inherit the [`use_directory_urls`]
+ [mkdocs.use_directory_urls] setting for all projects from the top-level
+ configuration:
+
+ ``` py title="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
+ ```
+
+ [module search path]: https://docs.python.org/3/library/sys_path_init.html
+ [PYTHONPATH]: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH
+ [python-name]: https://pyyaml.org/wiki/PyYAMLDocumentation#yaml-tags-and-python-types
+ [PyYAML]: https://pyyaml.org/
+
### Hoisting
The following settings are available for hoisting:
diff --git a/docs/schema/plugins/projects.json b/docs/schema/plugins/projects.json
index 7ed61e2e1..e8d42329a 100644
--- a/docs/schema/plugins/projects.json
+++ b/docs/schema/plugins/projects.json
@@ -50,6 +50,22 @@
"type": "string",
"default": "projects"
},
+ "projects_config_files": {
+ "title": "Projects configuration files",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.projects_config_files",
+ "type": "string",
+ "default": "\"*/mkdocs.yml\""
+ },
+ "projects_config_transform": {
+ "title": "Projects configuration transform",
+ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.projects_config_transform",
+ "type": "string",
+ "defaultSnippets": [
+ {
+ "body": "!!python/name:${1:module}.${2:function}"
+ }
+ ]
+ },
"hosting": {
"title": "Enable hoisting",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.hoisting",