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. Notably, Material for MkDocs offers offline support for many of its features.

Configuration¶

Built-in offline plugin¶

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

The plugin will automatically disable the use_directory_urls setting, 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.

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.