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.

Configuration¶

Built-in offline plugin¶

Sponsors only · insiders-4.10.0 · Plugin

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:

plugins:
  - offline # (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.¹

If you need to be able to build your documentation with and without Insiders, please refer to the built-in plugins section to learn how shared configurations help to achieve this.

The plugin will automatically disable use_directory_urls via mkdocs.yml, ensuring that users can open your documentation directly from the local file system.

The following configuration options are available:

enabled

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:

plugins:
  - offline:
      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.

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.

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.

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. ↩