Added documentation for offline plugin

Author: squidfunk

docs/setup/building-for-offline-usage.md

@@ -0,0 +1,93 @@
+---
+template: overrides/main.html
+---
+
+# Building for offline usage
+
+If you want to ship your documentation together with your product, MkDocs has
+you covered – with support from themes, [MkDocs] allows for building
+offline-capable documentation. Luckily, Material for MkDocs offers offline
+support for many of its features.
+
+  [MkDocs]: https://www.mkdocs.org
+
+## Configuration
+
+### Built-in offline plugin
+
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-4.10.0][Insiders] ·
+:octicons-cpu-24: Plugin ·
+:octicons-beaker-24: Experimental
+
+The built-in offline plugin makes sure that the [site search] works when you
+distribute the contents of your [site directory] as a download. Simply add
+the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+  - offline # (1)!
+```
+
+1.  Note that the offline plugin should be located at the end of the list of
+    `plugins`, as it will post-process the search index. If you want to use
+    other plugins that alter the search index together with this plugin, add
+    them before the built-in offline plugin.[^1]
+
+  [^1]:
+    Offline search was previously implemented through the third-party 
+    [localsearch] plugin, which is still possible if you don't want to use
+    [Insiders]. Note, however, that setup might be challenging if you're not
+    experienced with MkDocs.
+
+The plugin will automatically disable [`use_directory_urls`][use_directory_urls]
+via `mkdocs.yml`, ensuring that the user can open your documentation directly
+from the local file system.
+
+The following configuration options are available:
+
+`enabled`{ #enabled }
+
+:   :octicons-milestone-24: Default: `true` – This option specifies whether
+    the plugin is enabled when building your project. If you want to switch
+    the plugin off, e.g. for local builds, use an [environment variable]:
+
+    ``` yaml
+    plugins:
+      - privacy:
+          enabled: !ENV [OFFLINE, false]
+    ```
+
+Now, after invoking `mkdocs build`, you can open `site/index.html` directly
+in your browser and the [site search] will work as if the documentation was
+hosted on a regular server.
+
+!!! tip "Automatically bundle all external assets"
+
+    The brand-new [built-in privacy plugin] makes it easy to use external assets
+    while building documentation for offline usage, as it will automatically
+    download all external assets to distribute them with your documentation.
+
+  [Insiders]: ../insiders/index.md
+  [site search]: setting-up-site-search.md
+  [site directory]: https://www.mkdocs.org/user-guide/configuration/#site_dir
+  [localsearch]: https://github.com/wilhelmer/mkdocs-localsearch/
+  [use_directory_urls]: https://www.mkdocs.org/user-guide/configuration/#use_directory_urls
+  [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
+  [built-in privacy plugin]: ensuring-data-privacy.md#built-in-privacy-plugin
+
+#### Limitations
+
+Material for MkDocs offers many interactive features, some of which will not
+work from the file system due to the restrictions of modern browsers: all
+features that use the `fetch` API will error.
+
+Thus, when building for offline usage, make sure to disable the following
+configuration settings: [instant loading], [site analytics], [git repository],
+[versioning] and [comment systems].
+
+  [Instant loading]: setting-up-navigation.md#instant-loading
+  [Site analytics]: setting-up-site-analytics.md
+  [Versioning]: setting-up-versioning.md
+  [Git repository]: adding-a-git-repository.md
+  [Comment systems]: adding-a-comment-system.md

docs/setup/changing-the-logo-and-icons.md

@@ -84,7 +84,7 @@ theme:
 In order to use custom icons, [extend the theme] and create a new folder named
 `.icons` in the [`custom_dir`][custom_dir] you want to use for overrides.
 Next, add your `*.svg` icons into a subfolder of the `.icons` folder. Let's say
-you  downloaded and unpacked the [Bootstrap] icon set, and want to add it to
+you downloaded and unpacked the [Bootstrap] icon set, and want to add it to
 your project documentation. The structure of your project should look like this:
 
 ``` sh

docs/setup/ensuring-data-privacy.md

@@ -7,7 +7,7 @@ template: overrides/main.html
 Material for MkDocs makes compliance with data privacy regulations very easy, 
 as it offers a native [cookie consent] solution to seek explicit consent from
 users before setting up [tracking]. Additionally, external assets can be
-automatically bundled as part of the build process.
+automatically downloaded for self-hosting.
 
   [cookie consent]: setting-up-site-analytics.md#cookie-consent
   [tracking]: setting-up-site-analytics.md
@@ -22,8 +22,8 @@ automatically bundled as part of the build process.
 :octicons-beaker-24: Experimental
 
 The built-in privacy plugin automatically identifies [external assets] as part
-of the build process and allows to download and serve them as part of your site.
-Add the following to `mkdocs.yml`:
+of the build process and download all assets for dead simple self-hosting. Add
+the following lines to `mkdocs.yml`:
 
 ``` yaml
 plugins:
@@ -65,9 +65,13 @@ The following configuration options are available:
     If you've removed all external assets from your project via [customization],
     it's still a good idea to enable the plugin and set the mode to `report`,
     as the plugin will make sure that there are no hidden external links in any
-    Markdown files that were unintentionally added to the build.
+    Markdown files that were unintentionally added.
+
+    Using `report` in [strict mode] will make the build fail when external
+    assets are detected.
 
     [customization]: ../customization.md
+    [strict mode]: https://www.mkdocs.org/user-guide/configuration/#strict
 
 `externals_directory`{ #externals-directory }
 

docs/setup/setting-up-site-search.md

@@ -305,37 +305,6 @@ clipboard.
 
   [search.share support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
 
-### Offline search
-
-[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.7.0][Insiders] ·
-:octicons-beaker-24: Experimental
-
-Insiders makes sure that the built-in search also works when you distribute your
-documentation as `*.html` files for download. Simply add the following lines to
-`mkdocs.yml`:
-
-``` yaml
-use_directory_urls: false
-```
-
-This ensures that `index.html` is appended to all internal URLs, which is
-necessary for allowing users to view your documentation locally and without
-Internet connection. No further setup is necessary – your documentation will
-work online and offline without any further ado.[^1]
-
-Now, after invoking `mkdocs build`, you can open `site/index.html` directly
-in your browser and the built-in search will work as if the documentation was
-hosted on a regular server.
-
-  [^1]:
-    Offline search was previously implemented through the third-party 
-    [localsearch] plugin, which is still possible if you don't want to use
-    [Insiders]. Note, however, that setup might be challenging if you're not
-    experienced with MkDocs.
-
-  [localsearch]: https://github.com/wilhelmer/mkdocs-localsearch/
-
 ## Usage
 
 ### Search boosting

mkdocs.yml

@@ -187,6 +187,7 @@ nav:
     - Setting up the footer: setup/setting-up-the-footer.md
     - Adding a git repository: setup/adding-a-git-repository.md
     - Adding a comment system: setup/adding-a-comment-system.md
+    - Building for offline usage: setup/building-for-offline-usage.md
     - Extensions:
       - setup/extensions/index.md
       - Python Markdown: setup/extensions/python-markdown.md