diff --git a/docs/insiders/index.md b/docs/insiders/index.md index d226e691a..ec5003a86 100644 --- a/docs/insiders/index.md +++ b/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:
+- [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 diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md index 34c1d8539..0e36630b7 100644 --- a/docs/reference/code-blocks.md +++ b/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] · diff --git a/docs/setup/building-an-optimized-site.md b/docs/setup/building-an-optimized-site.md index 1486530de..24c1837e1 100644 --- a/docs/setup/building-an-optimized-site.md +++ b/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] · diff --git a/docs/setup/ensuring-data-privacy.md b/docs/setup/ensuring-data-privacy.md index 7712c76a1..779ec634b 100644 --- a/docs/setup/ensuring-data-privacy.md +++ b/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.