Skip to main content

convert mkdocs´ html output to mallard/yelp xml

Project description

html2mallard / mkdocs-mallard

Extremely crude HTML to mallard help conversion. Specifically for output from mkdocs with RTD or Material theme.

It's a very basic regex extraction (→I'm looking forward to your letters!) and filtering process. It only retains some structural elements (headlines, paragraphs, tables, lists, notes). Doesn't even attempt to gather any topic relation/structure from the navigation list.

  • Really just intended for one-time/initial conversion.
  • Requires some editing to get pages to validate. (Though they probably "work" in yelp as is).
  • Links and image references certainly require manual cleanup. Nested lists or tables are likely to cause issues.
  • And API docs are least convertible (only tested mkdocstrings, source dump is omitted, and there's obviously no syntax colorization in yelp; alternatively try mkgendocs).
  • Primarily designed for mkdocs´ HTML output. But also contains some cleanup rules for fossil wiki pages (with github skin), and yelp-builds` html.
  • Conversion doesn't work well for sphinx output (not consistent enough).


Simple command line tool to convert a single .html file:

html2mallard site/index.html > help/

Add a -d/--debug flag after the filename for details on the shortening process.

html2mallard in.html --debug | xmllint - --recover >

With xmllint to fix some unmatched tags.

  • Now also supports http:// urls for conversion:

     html2mallard http://wiki/index.html >
  • And directly converting from markdown:

     html2mallard >


Converts a list of mkdocs output files to *.page files.


Requires an extra mallard_dir in the mkdocs.yml config:

site_name: logfmt1
docs_dir: docs
site_dir: html
mallard_dir: mallard
use_directory_urls: false
  - Intro:
  name: readthedocs
  highlightjs: false
repo_url: https://...
  - admonition
  - codehilite
  - attr_list
  - def_list
  - tables
  - markdown.extensions.codehilite:
      guess_lang: true
  - mkdocstrings

Also depends on use_directory_urls: false, since the script only glob()s one level of *.html files.

Nav links

Ensure the contains a section like:

<section id="nav" style="2column">

But not the recursive self-reference <link type="guide" xref="index#nav"/>.


The first two rewrite rules likely require changes for other HTML sources or templates. Specifically "^.+?</nav>" should strip the initial boilerplate, else might need expansion. (Either in the GENERAL HTML or a new rewrite collection.)

from project import meta

meta info
depends -
compat Python ≥3.6, mkdocs 1.x
compliancy !pep8, mallard, manpage, !doap, !xdg
system usage -
paths -
testing -
docs -
activity abandoned
state alpha
support -
contrib -
announce -

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

html2mallard-0.2.2-py3-none-any.whl (8.8 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page