Updated changelogs

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

docs/insiders/changelog.md

@@ -2,6 +2,14 @@
 
 ## Material for MkDocs Insiders
 
+### 4.42.0 <small>September 19, 2023</small> { 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 <small>September 11, 2023</small> { id="4.41.0" }
 
 - Improved multi-instance support for optimize plugin

docs/plugins/meta.md

@@ -181,9 +181,9 @@ The following settings are available for meta files:
 <!-- md:version insiders-4.21.0 -->
 <!-- md:default `.meta.yml` -->
 
-Use this setting to change the file  the plugin will look for when scanning
+Use this setting to change the meta file name the plugin will look for when
-the [`docs` directory][mkdocs.docs_dir]. It's normally not necessary to change
+scanning the [`docs` directory][mkdocs.docs_dir]. It's normally not necessary to
-this setting, but if you want to change it, use:
+change this setting, but if you want to change it, use:
 
 ``` yaml
 plugins:

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
+Additionally, the plugin automatically disables the [`use_directory_urls`]
-[`use_directory_urls`][mkdocs.use_directory_urls] setting, ensuring that users
+[mkdocs.use_directory_urls] setting, ensuring that users can open your
-can open your documentation directly from the local file system.
+documentation directly from the local file system.
 
 There are some [limitations].
 

docs/plugins/projects.md

@@ -223,6 +223,107 @@ automatically hoisted by the plugin.
 
 The provided path is resolved from the root directory.
 
+---
+
+#### <!-- md:setting config.projects_config_files -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.42.0 -->
+<!-- md:default `*/mkdocs.yml` -->
+
+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].
+
+---
+
+#### <!-- md:setting config.projects_config_transform -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.42.0 -->
+<!-- md:default none -->
+
+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:

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",