Merge branch 'master' into merge/piri-piri

CHANGELOG

@@ -1,3 +1,18 @@
+mkdocs-material-9.1.21+insiders-4.38.0 (2023-07-29)
+
+  * Added projects plugin for building nested projects
+  * Updated privacy plugin to new MkDocs API
+
+mkdocs-material-9.1.21+insiders-4.37.1 (2023-07-28)
+
+  * Updated MkDocs to 1.5.1
+  * Fixed deprecation warning in social plugin due to MkDocs upgrade
+  * Fixed #5772: Privacy plugin fails due to API change in MkDocs
+
+mkdocs-material-9.1.21 (2023-07-27)
+
+  * Fixed MkDocs 1.4 compat issue in social plugin (9.1.20 regression)
+
 mkdocs-material-9.1.20 (2023-07-27)
 
   * Fixed deprecation warnings for social plugin

docs/changelog/index.md

@@ -25,6 +25,10 @@
 - Updated MkDocs to 1.5.0
 - Fixed rendering of tags when announcement bar is present
 
+### 9.1.21 <small>July 27, 2023</small> { id="9.1.20" }
+
+- Fixed MkDocs 1.4 compat issue in social plugin (9.1.20 regression)
+
 ### 9.1.20 <small>July 27, 2023</small> { id="9.1.20" }
 
 - Updated Sanskrit translations

docs/insiders/changelog.md

@@ -2,6 +2,17 @@
 
 ## Material for MkDocs Insiders
 
+### 4.38.0 <small>July 29, 2023</small> { id="4.38.0" }
+
+- Added projects plugin for building nested projects
+- Updated privacy plugin to new MkDocs API
+
+### 4.37.1 <small>July 28, 2023</small> { id="4.37.1" }
+
+- Updated MkDocs to 1.5.1
+- Fixed deprecation warning in social plugin due to MkDocs upgrade
+- Fixed #5772: Privacy plugin fails due to API change in MkDocs
+
 ### 4.37.0 <small>July 7, 2023</small> { id="4.37.0" }
 
 - Added support for overriding social cards settings per page

docs/insiders/index.md

@@ -88,11 +88,12 @@ a handful of them, [thanks to our awesome sponsors]!
 ## What's in it for me?
 
 The moment you [become a sponsor][how to become a sponsor], you'll get __immediate
-access to 22 additional features__ that you can __start using now__, and
+access to 23 additional features__ that you can __start using now__, and
 which are currently exclusively available to sponsors:
 
 <div class="mdx-columns" markdown>
 
+- [x] [Projects plugin] :material-alert-decagram:{ .mdx-pulse title="Added on July 29, 2023" }
 - [x] [Instant prefetching] :material-alert-decagram:{ .mdx-pulse title="Added on June 15, 2023" }
 - [x] [Social plugin: custom layouts] :material-alert-decagram:{ .mdx-pulse title="Added on May 8, 2023" }
 - [x] [Social plugin: background images] :material-alert-decagram:{ .mdx-pulse title="Added on May 8, 2023" }
@@ -311,12 +312,14 @@ are released for general availability.
 
 #### $ 24,000 – Blockpaprika
 
+- [x] [Projects plugin]
 - [x] [Social plugin: custom layouts]
 - [x] [Social plugin: background images]
 - [x] [Code range selection]
 - [x] [Code annotations: custom selectors]
 - [ ] Code line wrap button
 
+  [Projects plugin]: ../setup/building-an-optimized-site.md#built-in-projects-plugin
   [Social plugin: custom layouts]: ../setup/setting-up-social-cards.md#customization
   [Social plugin: background images]: ../setup/setting-up-social-cards.md#+social.cards_layout_params.background_image
   [Code range selection]: ../reference/code-blocks.md#code-selection-button

docs/reference/code-blocks.md

@@ -162,7 +162,7 @@ theme:
   [Code annotations support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0
   [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
 
-#### Custom selectors :material-alert-decagram:{ .mdx-pulse title="Added on February 19, 2023" }
+#### Custom selectors
 
 [:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
 [:octicons-tag-24: insiders-4.32.0][Insiders] ·

docs/schema/plugins.json

@@ -40,6 +40,9 @@
         {
           "$ref": "plugins/privacy.json"
         },
+        {
+          "$ref": "plugins/projects.json"
+        },
         {
           "$ref": "plugins/search.json"
         },

docs/schema/plugins/optimize.json

@@ -24,8 +24,7 @@
             "concurrency": {
               "title": "Concurrency (number of CPUs)",
               "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+optimize.concurrency",
-              "type": "number",
+              "type": "number"
-              "default": 1
             },
             "cache": {
               "title": "Enable caching",

docs/schema/plugins/privacy.json

@@ -24,8 +24,7 @@
             "concurrency": {
               "title": "Concurrency (number of CPUs)",
               "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.concurrency",
-              "type": "number",
+              "type": "number"
-              "default": 1
             },
             "assets": {
               "title": "Process external assets",

docs/schema/plugins/projects.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "title": "Built-in projects plugin",
+  "oneOf": [
+    {
+      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#built-in-projects-plugin",
+      "enum": [
+        "projects"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "projects": {
+          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#built-in-projects-plugin",
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "title": "Enable plugin",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+projects.enabled",
+              "type": "boolean",
+              "default": true
+            },
+            "concurrency": {
+              "title": "Concurrency (number of CPUs)",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+projects.concurrency",
+              "type": "number"
+            },
+            "projects": {
+              "title": "Enable projects",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+projects.projects",
+              "type": "boolean",
+              "default": true
+            },
+            "projects_dir": {
+              "title": "Projects directory",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+projects.projects_dir",
+              "type": "string",
+              "default": "projects"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  ]
+}

docs/schema/plugins/social.json

@@ -24,8 +24,7 @@
             "concurrency": {
               "title": "Concurrency (number of CPUs)",
               "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.concurrency",
-              "type": "number",
+              "type": "number"
-              "default": 1
             },
             "cards": {
               "title": "Social cards",

docs/setup/building-an-optimized-site.md

@@ -9,7 +9,116 @@ further useful automatic optimization techniques.
 
 ## Configuration
 
-### Built-in optimize plugin :material-alert-decagram:{ .mdx-pulse title="Added on January 21, 2023" }
+### Built-in projects plugin :material-alert-decagram:{ .mdx-pulse title="Added on July 29, 2023" }
+
+[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-4.38.0][Insiders] ·
+:octicons-cpu-24: Plugin ·
+:octicons-beaker-24: Experimental
+
+The built-in projects plugin allows to split your documentation into multiple
+distinct MkDocs projects, __build them concurrently__ and
+__serve them together__. Add the following to `mkdocs.yml`:
+
+``` yaml
+plugins:
+  - projects
+```
+
+Next, create a folder called `projects` in your root directory which will
+contain all projects. For example, if we want to build a project with two
+additional languages, we can use:
+
+``` { .sh .no-copy }
+.
+├─ projects/
+│  ├─ de/
+│  │  ├─ docs/
+│  │  └─ mkdocs.yml
+│  └─ fr/
+│     ├─ docs/
+│     └─ mkdocs.yml
+└─ mkdocs.yml
+```
+
+If you now invoke `mkdocs serve` and change a file in one of the projects,
+the projects plugin makes sure that MkDocs will also reload those files. Note
+that the projects are currently entirely separate, which means they will have
+separate search indexes and sitemaps. We're happy to receive feedback on this
+plugin and learn about your requirements to make it better, as we plan to add
+support for merging and hoisting files.
+[Create a discussion to share your thoughts!][discussion]
+
+  [discussion]: https://github.com/squidfunk/mkdocs-material/discussions
+
+??? info "Use cases for the projects plugin"
+
+    Ideal use cases for the projects plugin are:
+
+    - Building a multi-language site
+    - Building a blog alongside your documentation
+    - Splitting large code bases for better performance
+
+    Note that the plugin is currently experimental. We're releasing it early,
+    so that we can improve it together with our users and make it even more
+    powerful as we discover new use cases.
+
+The following configuration options are available:
+
+[`enabled`](#+projects.enabled){ #+projects.enabled }
+
+:   :octicons-milestone-24: Default: `true` – This option specifies whether
+    the plugin is enabled when building your project. If you want to speed up
+    local builds, you can use an [environment variable]:
+
+    ``` yaml
+    plugins:
+      - projects:
+          enabled: !ENV [CI, false]
+    ```
+
+[`concurrency`](#+projects.concurrency){ #+projects.concurrency }
+
+:   :octicons-milestone-24: Default: _number of CPUs_ – This option specifies
+    how many CPUs the plugin is allowed to use when building projects.
+    With more CPUs, the plugin can do more work in the same time, thus complete
+    optimization faster. Concurrent processing can be disabled with:
+
+    ``` yaml
+    plugins:
+      - projects:
+          concurrency: 1
+    ```
+
+#### Projects
+
+The following configuration options are available for projects:
+
+[`projects`](#+projects.projects){ #+projects.projects }
+
+:   :octicons-milestone-24: Default: `true` – This option specifies whether
+    to build nested projects. If you want to switch the plugin off, e.g.
+    for local builds, you can use an [environment variable]:
+
+    ``` yaml
+    plugins:
+      - projects:
+          projects: !ENV [CI, false]
+    ```
+
+[`projects_dir`](#+projects.projects_dir){ #+projects.projects_dir }
+
+:   :octicons-milestone-24: Default: `projects` – This option specifies the
+    name of the folder the plugin expects your projects to be stored. While it's
+    usually not necessary to change this option, change it with:
+
+    ``` yaml
+    plugins:
+      - projects:
+          projects_dir: path/to/folder
+    ```
+
+### Built-in optimize plugin
 
 [:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
 [:octicons-tag-24: insiders-4.29.0][Insiders] ·

docs/setup/ensuring-data-privacy.md

@@ -179,7 +179,7 @@ The following configuration options are available:
           enabled: !ENV [CI, false]
     ```
 
-[`concurrency`](#+privacy.concurrency){ #+privacy.concurrency } :material-alert-decagram:{ .mdx-pulse title="Added on February 6, 2023" }
+[`concurrency`](#+privacy.concurrency){ #+privacy.concurrency }
 
 :   :octicons-milestone-24: Default: _number of CPUs_ – This option specifies
     how many CPUs the plugin is allowed to use when downloading external assets.

package.json

@@ -50,13 +50,13 @@
   "devDependencies": {
     "@fortawesome/fontawesome-free": "^6.4.0",
     "@mdi/svg": "^7.2.96",
-    "@primer/octicons": "^19.4.0",
+    "@primer/octicons": "^19.5.0",
     "@types/css-modules": "^1.0.2",
     "@types/escape-html": "^1.0.2",
     "@types/fuzzaldrin-plus": "^0.6.2",
     "@types/html-minifier": "^4.0.2",
     "@types/lunr": "^2.3.4",
-    "@types/node": "^20.4.4",
+    "@types/node": "^20.4.5",
     "@types/resize-observer-browser": "^0.1.7",
     "@types/sass": "^1.45.0",
     "@typescript-eslint/eslint-plugin": "5.62.0",
@@ -64,11 +64,11 @@
     "autoprefixer": "^10.4.14",
     "chokidar": "^3.5.3",
     "cssnano": "5.1.0",
-    "esbuild": "^0.18.16",
+    "esbuild": "^0.18.17",
-    "eslint": "^8.45.0",
+    "eslint": "^8.46.0",
     "eslint-plugin-eslint-comments": "^3.2.0",
-    "eslint-plugin-import": "^2.27.5",
+    "eslint-plugin-import": "^2.28.0",
-    "eslint-plugin-jsdoc": "^46.4.4",
+    "eslint-plugin-jsdoc": "^46.4.5",
     "eslint-plugin-no-null": "^1.0.2",
     "github-types": "^1.0.0",
     "gitlab": "^14.2.2",
@@ -76,7 +76,7 @@
     "html-minifier": "^4.0.0",
     "material-design-color": "^2.3.2",
     "material-shadows": "^3.0.1",
-    "npm-check-updates": "^16.10.16",
+    "npm-check-updates": "^16.10.17",
     "npm-run-all": "^4.1.5",
     "postcss": "^8.4.27",
     "postcss-dir-pseudo-class": "^8.0.0",
@@ -86,7 +86,7 @@
     "preact": "^10.16.0",
     "rimraf": "^5.0.1",
     "sass": "^1.64.1",
-    "simple-icons": "^9.7.0",
+    "simple-icons": "^9.8.0",
     "stylelint": "^15.10.2",
     "stylelint-config-recess-order": "4.2.0",
     "stylelint-config-recommended": "^13.0.0",

requirements.txt

@@ -21,7 +21,7 @@
 # Requirements for core
 jinja2>=3.0
 markdown>=3.2
-mkdocs>=1.5
+mkdocs>=1.5.1
 mkdocs-material-extensions>=1.1
 pygments>=2.14
 pymdown-extensions>=9.9.1