Artifact [261f491f57]
Artifact 261f491f57483525d7f580a016a63f23bfa3cdfabd13a700c93fd52ea69557de:
- File html2mallard/README.md — part of check-in [1aa3926f1f] at 2021-01-12 22:48:34 on branch trunk — html2mallard 0.2 with material theme recognition, slightly more structured regex rules (user: mario size: 3864)
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.
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.
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 | - |