MkDocs plugin to generate a manpage from the documentation site.

Pandoc must be installed and available as pandoc.

pip install mkdocs-manpage[preprocess]

# mkdocs.yml plugins: - manpage: pages: - title: My Project # defaults to site name output: share/man/man1/my-project.1 inputs: - index.md - usage.md - title: my-project API header: Python Library APIs # defaults to common header for section 3 (see `man man`) output: share/man/man3/my_project.3 inputs: - reference/my_project/*.md

To enable/disable the plugin with an environment variable:

# mkdocs.yml plugins: - manpage: enabled: !ENV [MANPAGE, false]

Then set the environment variable and run MkDocs:

MANPAGE=true mkdocs build

This plugin works by concatenating the HTML from all selected pages into a single file that is then converted to a manual page using Pandoc.

With a complete conversion, the final manual page will not look so good. For example images and SVG will be rendered as long strings of data and/or URIs. So this plugin allows users to pre-process the HTML, to remove unwanted HTML elements before converting the whole thing to a manpage.

First, you must make sure to install the preprocess extra:

pip install mkdocs-manpage[preprocess]

To pre-process the HTML, we use BeautifulSoup. Users have to write their own preprocess function in order to modify the soup returned by BeautifulSoup:

from bs4 import BeautifulSoup, Tag def to_remove(tag: Tag) -> bool: # remove images and SVGs if tag.name in {"img", "svg"}: return True # remove links containing images or SVGs if tag.name == "a" and tag.img and to_remove(tag.img): return True # remove permalinks if tag.name == "a" and "headerlink" in tag.get("class", ()): return True return False def preprocess(soup: BeautifulSoup, output: str) -> None: for element in soup.find_all(to_remove): element.decompose()

Then, instruct the plugin to use this module and its preprocess function:

plugins: - manpage: preprocess: scripts/preprocess.py

See the documentation of both [BeautifulSoup][bs4.BeautifulSoup] and [Tag][bs4.Tag] to know what methods are available to correctly select the elements to remove.

The alternative to HTML processing for improving the final manpage is disabling some options from other plugins/extensions:

• no source code through mkdocstrings:

  - mkdocstrings: handlers: python: options: show_source: !ENV [SHOW_SOURCE, true]

• no permalink through toc:

  markdown_extensions: - toc: permalink: !ENV [PERMALINK, true]

Then set these environment variables before building the documentation and generating the manpage:

export MANPAGE=true export PERMALINK=false export SHOW_SOURCE=false mkdocs build