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

html2mallard

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

html2mallard site/index.html > help/index.page

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

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

With xmllint to fix some unmatched tags.

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

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

     html2mallard index.md > index.page
    

mkdocs-mallard

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

mkdocs-mallard

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
nav:
  - Intro: index.md
theme:
  name: readthedocs
  highlightjs: false
repo_url: https://...
markdown_extensions:
  - admonition
  - codehilite
  - attr_list
  - def_list
  - tables
  - markdown.extensions.codehilite:
      guess_lang: true
plugins:
  - mkdocstrings

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

Nav links

Ensure the index.page contains a section like:

<section id="nav" style="2column">
 <subtitle>Topics</subtitle>
</section>

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

Adaption

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.

Built Distribution

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

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page