randogoth/md2txt
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Move the WML renderer out to wapdown

Browse source 
Every other renderer here -- text, micron, ama, gemini, nex -- is a
straight transform of a document into a flat, minimal text format. The
WML renderer was neither: it emitted an XML tree, and it restructured the
document rather than transforming it, splitting one file into many
<card>s and inventing navigation between them. That is why it was the
only renderer needing split_level / max_card_bytes / menu levers, the
only one buffering the whole event stream instead of streaming it, and
the only one that required a block kind in the shared parser --
CARD_BREAK, for its {.card} divider -- that every other renderer ignored
as a no-op.

It now lives in its own repository, where restructuring a document into a
navigable deck is the point rather than an intrusion:

    https://codeberg.org/randogoth/wapdown

Removed here: renderers/wml.py, its CLI registration, the wml examples,
the README section, and the CARD_BREAK event and {.card} directive that
existed solely to serve it. A leftover {.card} line in an old document
will now render as literal text rather than being silently dropped.

Verified: all five remaining renderers produce byte-identical output to
before this change.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
randogoth 2026-09-23 09:01:40 +03:00
parent d5046543b3
commit e708dce8f7
8 changed files with 12 additions and 544 deletions
Download patch file Download diff file Expand all files Collapse all files

44
README.md
View file

@ -19,7 +19,7 @@ uv tool install --from git+https://codeberg.org/randogoth/md2txt/ md2txt
## CLI
- `md2txt` – converts Markdown into plain text with extensive formatting support. It ships with the default `markdown` parser and `text` renderer plugins, registers optional `micron`, `ama`, `gemini`, and `wml` renderers for Micron/Ancient Machine Book, Gemtext, or WML (WAP) output, and exposes the core pipeline so you can add your own parser or renderer modules:
- `md2txt` – converts Markdown into plain text with extensive formatting support. It ships with the default `markdown` parser and `text` renderer plugins, registers optional `micron`, `ama`, `gemini`, and `nex` renderers for Micron/Ancient Machine Book, Gemtext, or Nex output, and exposes the core pipeline so you can add your own parser or renderer modules:
- FIGlet-rendered headings.
- Emphasis styles converted to spaced or delimited characters.
- Optional alignment and margin controls via HTML `<p>` attributes or MultiMarkdown attribute blocks (e.g. `{:.center margin=20px}`) applied as leading spaces.
@ -36,7 +36,7 @@ md2txt input.md --width 72 # override column width
md2txt input.md --renderer micron # emit Micron-formatted output for NomadNet
md2txt input.md --renderer ama # emit AMA markup for Ancient Machine Book
md2txt input.md --renderer gemini # emit Gemtext for Gemini capsules
md2txt input.md --renderer wml # emit a single-card WML deck for WAP browsers
md2txt input.md --renderer nex # emit plain text for Nex capsules
md2txt input.md --renderer-option width=68 # pass column width to a renderer
```
@ -123,39 +123,13 @@ Inline or block-level ASCII art can be embedded directly in Markdown:
Generated text uses CRLF line endings to maintain DOS compatibility.
## WML Decks
## Nex
The `wml` renderer converts Markdown into a [WML](https://en.wikipedia.org/wiki/Wireless_Markup_Language) deck for old WAP browsers. WML screens are idiomatically short and button/link-navigated rather than one long scrolling page, so unlike the other renderers, `wml` can split a document into multiple `<card>`s — but only when you ask it to; a plain document with no options stays a single card.
The `nex` renderer converts Markdown into plain text for the [Nex](https://nightfall.city/nex/) protocol. Nex has no hypertext markup for hand-authored documents at all — its one special syntax, `=> URL`, is spec'd for server-auto-generated directory listings, not document bodies — so `nex` output is deliberately unmarked plain text, reusing `TextRenderer`'s wrapping/margin/hyphenation machinery (same approach as the `ama`/`micron` renderers):
Two independent, both-optional ways to define card boundaries:
- **Manual dividers** — insert a `{.card}` or `{.card Title}` line wherever you want a new card to start, regardless of heading structure:
```markdown
Intro shown on the menu card...
{.card Weather}
Cold and clear...
{.card Trail Status}
- North Loop: open
```
- **Heading-level splitting** — opt in with `--renderer-option split_level=N` to start a new card at every heading of level `N` (e.g. `split_level=2` for the common one-H1-title-plus-H2-sections pattern). Ignored if the document contains any `{.card}` markers.
When a document resolves to two or more cards, `wml` builds a "menu" card by default — the classic WAP-portal pattern: a list of button/link choices leading to each section, each with a Back control (`--renderer-option menu=false` switches to a linear book instead, chaining cards with Next/Back). A section whose content would still be too large for one card even after splitting is automatically paginated further (`--renderer-option max_card_bytes=N`, default 1400 — a nod to classic WAP 1.x per-deck cache limits; `0` disables it).
| Renderer option | Default | Meaning |
| --- | --- | --- |
| `title` | *(none)* | Overall deck title, used on the menu card (or the single card, if never split). |
| `split_level` | `0` (disabled) | Heading level that starts a new card. Ignored if `{.card}` markers are present. |
| `max_card_bytes` | `1400` | Byte safety-net per card; `0` disables. |
| `menu` | `true` | Hub-and-spoke menu card vs. linear Next/Back chaining (`menu=false`). |
| `nav_next_label` | `More` | Label for forward navigation (linear mode / overflow pagination). |
| `nav_prev_label` | `Prev` | Label for backward navigation between overflow pagination parts. |
| `nav_back_label` | `Back` | Label for backward navigation from a section back to the menu/previous section. |
WML 1.3 is the only supported DTD (fixed by design, not a flag). Since WML uses `$` for variable substitution, a literal `$` in your Markdown is escaped to `$$` in the output automatically. Images pass through as `<img src="..." alt="..."/>` referencing the original path/URL — no WBMP conversion is performed.
- Headings get a plain setext-style underline (`=` for H1, `-` for H2+) instead of a FIGlet banner. This is a readability convention borrowed from Markdown itself, not a requirement of the Nex spec.
- `**bold**`/`*italic*`/`~~strikethrough~~` markers are stripped rather than translated — there's nothing in Nex to translate them into.
- Links and images are inlined as `label (url)` plain prose (or bare `url` when there's no distinct label/alt, or when the label equals the url) rather than footnoted or turned into `=> ` lines, since that syntax isn't confirmed safe inside a regular document body.
## Plugin Architecture
@ -186,6 +160,10 @@ Once registered (for example in a small module that imports `md2txt.cli`), the n
The shared preprocessing helpers—YAML frontmatter parsing, recursive include expansion, ASCII art sentinels, and pipe-table sentinels—also live in `src/md2txt/conversion/core.py`, allowing alternate front-ends to reuse exactly the same behaviour without duplicating code.
## WML / WAP Output
The `wml` renderer used to live here. It has moved to [wapdown](https://codeberg.org/randogoth/wapdown), because a WML deck is not a minimal text format: it is an XML tree, and producing one means restructuring a document into navigable cards rather than transforming it. That needed controls the exporters here have no use for, so it now has a repository of its own. The `{.card}` divider moved with it.
---
* Directed and vibe coded by Tobias Raayoni Last