## html2mallard / mkdocs-mallard
Extremely crude HTML to [mallard help](http://projectmallard.org/)
conversion. Specifically for output from [mkdocs](https://www.mkdocs.org/)
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](https://pypi.org/project/mkgendocs/)).
* Primarily designed for mkdocs´ HTML output. But also contains some
cleanup rules for [fossil](https://fossil-scm.org/) wiki pages (with
[github](https://fossil.include-once.org/fossil-skins/wiki/GitHub) skin),
and yelp-builds` html.
* Conversion doesn't work well for sphinx output (not consistent enough),
nor GitHub wiki pages.
## 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](http://xmlsoft.org/xmllint.html) 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
## API
There's basically just one main function in html2mallard:
import html2mallard
page = html2mallard.convert(html_file_content, fn)
The filename parameter is just used to deduce id and/or title from.
As convenience method there is also `page = html2mallard.convert_file(fn)`,
which would also automatically invoke `markdown` conversion given such an
extension, or even resolve an url as parameter.
## 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 | - |