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