From eac707168b5efc090a357deceb92df3601922775 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 27 Feb 2022 15:08:31 +0100 Subject: [PATCH] Added documentation for offline plugin --- docs/setup/building-for-offline-usage.md | 93 +++++++++++++++++++++++ docs/setup/changing-the-logo-and-icons.md | 2 +- docs/setup/ensuring-data-privacy.md | 12 ++- docs/setup/setting-up-site-search.md | 31 -------- mkdocs.yml | 1 + 5 files changed, 103 insertions(+), 36 deletions(-) create mode 100644 docs/setup/building-for-offline-usage.md diff --git a/docs/setup/building-for-offline-usage.md b/docs/setup/building-for-offline-usage.md new file mode 100644 index 000000000..d5e1eafaf --- /dev/null +++ b/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 diff --git a/docs/setup/changing-the-logo-and-icons.md b/docs/setup/changing-the-logo-and-icons.md index 43f6eeac8..f4f329afc 100644 --- a/docs/setup/changing-the-logo-and-icons.md +++ b/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 diff --git a/docs/setup/ensuring-data-privacy.md b/docs/setup/ensuring-data-privacy.md index 8818b427e..ae30b56b7 100644 --- a/docs/setup/ensuring-data-privacy.md +++ b/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 } diff --git a/docs/setup/setting-up-site-search.md b/docs/setup/setting-up-site-search.md index 5112cbd5a..68d5bb428 100644 --- a/docs/setup/setting-up-site-search.md +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index 400dab38d..ad05c93bf 100755 --- a/mkdocs.yml +++ b/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