1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
---
title: Built-in offline plugin
icon: material/connection
---
# Built-in offline plugin
[MkDocs][mkdocs] is one of the few frameworks that allow to build offline-capable
documentation that can be directly viewed by the user – no server needed. With
the offline plugin, you can distribute the [`site` directory][mkdocs.site_dir]
as a downloadable `.zip` file while retaining most interactive functionality.
## Objective
### How it works
After [building your project], switch to the [`site` directory][mkdocs.site_dir]
and open `index.html` in your browser – you're now viewing your documentation
from your local file system! Most browsers will denote this by showing `file://`
in the address bar. However, you'll realize that the site search is gone.
Material for MkDocs offers many interactive features, some of which will not
work from the local file system due to the restrictions of modern browsers. More
specifically and technically, all calls to the [Fetch API] will error with a
message like:
```
Cross origin requests are only supported for protocol schemes: http, [...]
```
While browsers impose those restriction for security reasons, it reduces the
interactivity of your project. The offline plugin makes sure that site search
keeps working by moving the search index to a JavaScript file, and leveraging
@squidfunk's [iframe-worker] shim.
Additionally, the plugin automatically disables the [`use_directory_urls`]
[mkdocs.use_directory_urls] setting, ensuring that users can open your
documentation directly from the local file system.
There are some [limitations].
[building your project]: ../creating-your-site.md#building-your-site
[Fetch API]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
[iframe-worker]: https://github.com/squidfunk/iframe-worker
[limitations]: #limitations
### When to use it
As the name already indicates, the plugin should only be used when you're
[building your project] for offline distribution. It's also good to know, that
the offline plugin plays nicely with the following other plugins, helping to
create even better offline-capable documentation:
<div class="grid cards" markdown>
- :material-shield-account: __[Built-in privacy plugin][privacy]__
---
The privacy plugin makes it easy to use external assets when building for
offline usage, as it automatically downloads them for distribution with
your documentation.
---
__Your documentation can work without connectivity to the internet[^1]__
- :material-rabbit: __[Built-in optimize plugin][optimize]__
---
The optimize plugin automatically identifies and optimizes all media files
that you reference in your project by using compression and conversion
techniques.
---
__Your documentation can be distributed as a smaller `.zip` download__
</div>
[^1]:
You might wonder why the [privacy plugin][privacy] is necessary to build
truly offline-capable documentation with the offline plugin. While it's
certainly possible to also add support for downloading external assets to
the offline plugin, this functionality is already fully implemented in the
privacy plugin and is its very raison d'être.
Material for MkDocs follows a modular approach for its plugin system – many
of the plugins work perfectly together and enhance each others
functionalities, allowing to solve complex problems with a few lines
of configuration.
[privacy]: privacy.md
[optimize]: optimize.md
## Configuration
<!-- md:version 9.0.0 -->
<!-- md:plugin [offline] – built-in -->
As with all [built-in plugins], getting started with the offline plugin is
straightforward. Just add the following lines to `mkdocs.yml`, and start
building offline-capable documentation:
``` yaml
plugins:
- offline
```
The offline plugin is built into Material for MkDocs and doesn't need to be
installed.
[offline]: offline.md
[built-in plugins]: index.md
### General
The following settings are available:
---
#### <!-- md:setting config.enabled -->
<!-- md:version 9.0.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable the plugin when [building your project].
If you want to build online- as well as offline-capable documentation, it's a
good idea to use an [environment variable][mkdocs.env]:
``` yaml
plugins:
- offline:
enabled: !ENV [OFFLINE, false]
```
## Limitations
When enabling the offline plugin, make sure to disable the following settings,
as they make use of the [Fetch API] which will error when invoked from the local
file system:
- [Instant loading]
- [Site analytics]
- [Versioning]
- [Comment systems]
[Instant loading]: ../setup/setting-up-navigation.md#instant-loading
[Site analytics]: ../setup/setting-up-site-analytics.md
[Versioning]: ../setup/setting-up-versioning.md
[Comment systems]: ../setup/adding-a-comment-system.md
|
