{"id":15057040,"url":"https://github.com/pawamoy/mkdocs-manpage","last_synced_at":"2026-02-26T06:21:22.039Z","repository":{"id":172884437,"uuid":"649918681","full_name":"pawamoy/mkdocs-manpage","owner":"pawamoy","description":"MkDocs plugin to generate a manpage from the documentation site.","archived":false,"fork":false,"pushed_at":"2024-03-31T19:11:36.000Z","size":808,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-11-14T17:52:23.686Z","etag":null,"topics":["manpage","manpages","mkdocs","mkdocs-plugin"],"latest_commit_sha":null,"homepage":"https://pawamoy.github.io/mkdocs-manpage/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pawamoy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"github":"pawamoy","ko_fi":"pawamoy","polar":"pawamoy","custom":["https://www.paypal.me/pawamoy"]}},"created_at":"2023-06-05T23:46:02.000Z","updated_at":"2024-11-13T03:08:55.000Z","dependencies_parsed_at":null,"dependency_job_id":"6900abe8-bcd5-4304-b729-e815e5379b6f","html_url":"https://github.com/pawamoy/mkdocs-manpage","commit_stats":null,"previous_names":["pawamoy/mkdocs-manpage"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pawamoy%2Fmkdocs-manpage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pawamoy%2Fmkdocs-manpage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pawamoy%2Fmkdocs-manpage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pawamoy%2Fmkdocs-manpage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pawamoy","download_url":"https://codeload.github.com/pawamoy/mkdocs-manpage/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225741250,"owners_count":17516894,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["manpage","manpages","mkdocs","mkdocs-plugin"],"created_at":"2024-09-24T22:01:14.427Z","updated_at":"2026-02-26T06:21:22.027Z","avatar_url":"https://github.com/pawamoy.png","language":"Python","funding_links":["https://github.com/sponsors/pawamoy","https://ko-fi.com/pawamoy","https://polar.sh/pawamoy","https://www.paypal.me/pawamoy"],"categories":[],"sub_categories":[],"readme":"# MkDocs Manpage\n\n\u003e [!WARNING]\n\u003e This project is in maintenance mode. I'm now dedicating my time to [Zensical](https://zensical.org/). Feel free to reach out for a responsible transfer of maintainership.\n\n[![ci](https://github.com/pawamoy/mkdocs-manpage/workflows/ci/badge.svg)](https://github.com/pawamoy/mkdocs-manpage/actions?query=workflow%3Aci)\n[![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)](https://pawamoy.github.io/mkdocs-manpage/)\n[![pypi version](https://img.shields.io/pypi/v/mkdocs-manpage.svg)](https://pypi.org/project/mkdocs-manpage/)\n[![gitter](https://badges.gitter.im/join%20chat.svg)](https://app.gitter.im/#/room/#mkdocs-manpage:gitter.im)\n\nMkDocs plugin to generate a manpage from the documentation site.\n\n## Requirements\n\nPandoc must be [installed](https://pandoc.org/installing.html) and available as `pandoc`.\n\n## Installation\n\n```bash\npip install mkdocs-manpage[preprocess]\n```\n\n## Usage\n\n```yaml\n# mkdocs.yml\nplugins:\n- manpage:\n    pages:\n    - title: My Project  # defaults to site name\n      output: share/man/man1/my-project.1\n      inputs:\n      - index.md\n      - usage.md\n    - title: my-project API\n      header: Python Library APIs  # defaults to common header for section 3 (see `man man`)\n      output: share/man/man3/my_project.3\n      inputs:\n      - reference/my_project/*.md\n```\n\nTo enable/disable the plugin with an environment variable:\n\n```yaml\n# mkdocs.yml\nplugins:\n- manpage:\n    enabled: !ENV [MANPAGE, false]\n```\n\nThen set the environment variable and run MkDocs:\n\n```bash\nMANPAGE=true mkdocs build\n```\n\n### Pre-processing HTML\n\nThis plugin works by concatenating the HTML from all selected pages\ninto a single file that is then converted to a manual page using Pandoc.\n\nWith a complete conversion, the final manual page will not look so good.\nFor example images and SVG will be rendered as long strings of data and/or URIs.\nSo this plugin allows users to pre-process the HTML, to remove unwanted\nHTML elements before converting the whole thing to a manpage.\n\nFirst, you must make sure to install the `preprocess` extra:\n\n```bash\npip install mkdocs-manpage[preprocess]\n```\n\nTo pre-process the HTML, we use [BeautifulSoup](https://pypi.org/project/beautifulsoup4/).\nUsers have to write their own `preprocess` function in order to modify the soup\nreturned by BeautifulSoup:\n\n```python title=\"scripts/preprocess.py\"\nfrom bs4 import BeautifulSoup, Tag\n\n\ndef to_remove(tag: Tag) -\u003e bool:\n    # remove images and SVGs\n    if tag.name in {\"img\", \"svg\"}:\n        return True\n    # remove links containing images or SVGs\n    if tag.name == \"a\" and tag.img and to_remove(tag.img):\n        return True\n    # remove permalinks\n    if tag.name == \"a\" and \"headerlink\" in tag.get(\"class\", ()):\n        return True\n    return False\n\n\ndef preprocess(soup: BeautifulSoup, output: str) -\u003e None:\n    for element in soup.find_all(to_remove):\n        element.decompose()\n```\n\nThen, instruct the plugin to use this module and its `preprocess` function:\n\n```yaml title=\"mkdocs.yml\"\nplugins:\n- manpage:\n    preprocess: scripts/preprocess.py\n```\n\nSee the documentation of both [`BeautifulSoup`][bs4.BeautifulSoup] and [`Tag`][bs4.Tag]\nto know what methods are available to correctly select the elements to remove.\n\nThe alternative to HTML processing for improving the final manpage\nis disabling some options from other plugins/extensions:\n\n- no source code through `mkdocstrings`:\n\n    ```yaml\n    - mkdocstrings:\n        handlers:\n          python:\n            options:\n              show_source: !ENV [SHOW_SOURCE, true]\n    ```\n\n- no permalink through `toc`:\n\n    ```yaml\n    markdown_extensions:\n    - toc:\n        permalink: !ENV [PERMALINK, true]\n    ```\n\nThen set these environment variables before building\nthe documentation and generating the manpage:\n\n```bash\nexport MANPAGE=true\nexport PERMALINK=false\nexport SHOW_SOURCE=false\nmkdocs build\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpawamoy%2Fmkdocs-manpage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpawamoy%2Fmkdocs-manpage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpawamoy%2Fmkdocs-manpage/lists"}