MkDocs Print Site Plugin

2.8 · active · verified Fri Apr 17

The mkdocs-print-site-plugin is an MkDocs plugin designed to combine all documentation pages into a single, printable HTML page. This allows for easy export to PDF and creates a standalone HTML file, useful for offline viewing or comprehensive sharing. It is actively maintained with frequent updates, currently at version 2.8.

Common errors

```
Plugin 'print-site' is not found
```
cause The plugin has not been installed or its name is misspelled in the `mkdocs.yml` configuration.

fix Run `pip install mkdocs-print-site-plugin` to install the package and ensure `print-site` is correctly listed under the `plugins:` section in your `mkdocs.yml`.
```
ERROR - Config value 'plugins' must be a list of strings or dicts
```
cause The `print-site` plugin is not configured correctly in `mkdocs.yml`, often due to incorrect YAML indentation or improper list formatting under `plugins:`.

fix Ensure `print-site` is an item in a YAML list under `plugins:`, for example: ```yaml plugins: - print-site ```
```
ERROR - The 'print-site' plugin encountered an error: 'NoneType' object has no attribute 'h1'
```
cause A page in your documentation is missing an H1 heading, and you are using a version of the plugin older than v2.5.0 which required all pages to have an H1.

fix Upgrade `mkdocs-print-site-plugin` to v2.5.0 or newer. Alternatively, ensure all documentation pages have at least one H1 heading.
```
WARNING - Plugin 'print-site' has already been loaded from '<some_path>'. Ignoring new instance from '<another_path>'.
```
cause The `print-site` plugin is listed multiple times in the `plugins` section of your `mkdocs.yml` file.

fix Review your `mkdocs.yml` and remove any duplicate entries for `print-site` from the `plugins` list.

Warnings

breaking Prior to v2.3.6, the plugin could break with MkDocs 1.5 due to changes in how `extra_javascript` was handled, leading to build failures or incorrect script loading.
Fix: Upgrade `mkdocs-print-site-plugin` to v2.3.6 or newer. Ensure your MkDocs version is compatible with the plugin's requirements.
gotcha Before version 2.5.0, pages without an H1 heading would cause an error during site generation. This was a common footgun for users with less structured pages.
Fix: Upgrade `mkdocs-print-site-plugin` to v2.5.0 or newer, which adds support for pages with missing H1 tags. Alternatively, ensure all pages have at least one H1 heading.
gotcha While often flexible, for some MkDocs hooks or other plugins, the order of `print-site` in the `plugins` list could lead to unexpected behavior or warnings. v2.6.0 addressed invalid warnings, but complex setups might still require careful ordering.
Fix: If encountering issues with other plugins, try adjusting the order of `print-site` in your `mkdocs.yml` `plugins` list. Place `print-site` later in the list if it needs to process output from other plugins.
gotcha Prior to v2.7.1, the `exclude()` function in the plugin configuration might not correctly deal with excluding entire folders, leading to unwanted pages appearing in the print output.
Fix: Upgrade `mkdocs-print-site-plugin` to v2.7.1 or newer to ensure correct folder exclusion behavior.

Install

pip install mkdocs-print-site-plugin Install plugin

Quickstart

To enable the print-site plugin, add it to the `plugins` section of your `mkdocs.yml` file. After building your site (`mkdocs build`), a new 'print-site' page will be generated at the root of your site, typically accessible at `/print_page/` or `your-site.com/print_page/`.

site_name: My Docs

plugins:
  - print-site

view raw JSON →