MkDocs Manpage

MkDocs插件，可以从文档网站生成manpage。

需求

Pandoc必须安装，并作为pandoc可用。

安装

使用pip

pip install mkdocs-manpage[preprocess]

使用pipx

python3.8 -m pip install --user pipx
pipx 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

使用环境变量启用/禁用插件

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

然后设置环境变量并运行MkDocs

MANPAGE=true mkdocs build

预处理HTML

此插件通过将所有选定的HTML页面连接成一个文件，然后使用Pandoc将其转换为manpage。

完整转换后，最终的manpage可能看起来不太美观。例如，图像和SVG将被渲染为长字符串的数据和/或URI。因此，此插件允许用户预处理HTML，在将整个内容转换为manpage之前删除不需要的HTML元素。

首先，您必须确保安装了preprocess扩展

pip install mkdocs-manpage[preprocess]

要预处理HTML，我们使用BeautifulSoup。用户必须编写自己的preprocess函数来修改BeautifulSoup返回的soup

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()

然后，指示插件使用此模块及其 preprocess 函数

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

参阅 [BeautifulSoup][bs4.BeautifulSoup] 和 [Tag][bs4.Tag] 的文档，了解可用的方法以正确选择要删除的元素。

为了改进最终的手册页面，HTML处理的替代方法是禁用其他插件/扩展的某些选项

• 通过 mkdocstrings 没有源代码

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

• 通过 toc 没有永久链接

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

然后在构建文档和生成手册页面之前设置这些环境变量

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