myform 0.7.0

A typed translator that reads MyST and GFM and writes MyST, GFM, rST, and Typst.

myform

Status: In development — the package has not had its first public release. Expect breaking changes.

myform is a universal docs-format translator built around one absolute, typed document tree. It reads MyST Markdown and GitHub Flavored Markdown (GFM), then writes idiomatic MyST, GFM, Sphinx reStructuredText, or Typst. Formatting is the identity case: myform.convert(text, format, format) runs through the same reader, typed tree, and writer as a cross-format conversion.

Format	Read	Write
MyST Markdown	Yes	Yes
GFM	Yes	Yes
Sphinx reStructuredText	No	Yes
Typst	No	Yes

The two Markdown identity conversions remain the compatibility rail. They produce byte-for-byte the same text as the existing mdformat pipelines, including the MyST opinions developed in this repository.

Develop from source

Until the first myform release, install the checked-out source with uv:

uv sync --all-extras
uv run myform --help

After the first public release, the package installation command will be:

pip install myform

Translate documents

uv run myform convert guide.md --from myst --to rst -o guide.rst
printf '# Hello\n' | uv run myform convert - --from gfm --to typst
uv run myform convert guide.md --from myst --to gfm --report json >guide.gfm

Use - as the input path to read stdin. Output goes to stdout unless -o/--output names a file. Conversion reports always go to stderr, keeping document output safe for pipelines. Choose --report summary (the default), --report json, or --report none.

Format documents

The format verb performs an identity conversion:

uv run myform format README.md
uv run myform format README.md --format myst -o README.formatted.md

The Python API exposes the same contract:

import myform

rst = myform.convert(source, 'myst', 'rst')
formatted = myform.convert(source, 'myst', 'myst')

Configure translation

myform discovers the nearest myform.yaml, .myform.yaml, or [tool.myform] table by walking upward from the target path. Within one directory, that order is also the precedence order. The nearest directory wins rather than merging several files.

degrade:
  mode: annotate
  comments: true
assist:
  enabled: false
typst:
  postformat: off
extensions: []

Every non-native conversion is represented in the conversion report. The default annotate degradation mode also leaves a provenance comment when the target supports comments; silent suppresses comments but not reports, while strict refuses carrying or dropping unsupported constructs.

The optional LM assist is degradation-only and disabled by default, which makes zero network calls. When enabled, it uses the configured local OpenAI-compatible gateway and retains a deterministic fallback.

The committed myform.schema.json and myst-options.schema.json schemas describe the translator and mdformat-facade configuration surfaces. Refresh or verify both with:

uv run myform-write-schema
uv run myform-write-schema --check

Use the MyST mdformat facade

The original plugin remains available through mdformat's myst extension entry point:

uv run mdformat README.md

This repository began as a ground-up rewrite of mdformat-myst, written to make uncompiled MyST documents look closer to the hand-formatted sources maintained by the MyST team. That facade remains useful on its own:

1. Targets hug the headings or blocks they identify instead of being separated by an extra blank line.

2. Directive options prefer the readable :key: value prefix form and escalate to a YAML block only when necessary.

3. Directive contents are formatted as first-class Markdown rather than treated as opaque text.

4. Parser and renderer rules are explicit, decorator-registered examples of a modern mdformat extension.

5. YAML values use srsly's maintained ruamel.yaml integration.

6. The optional sembr mode reflows paragraphs to one sentence per line without changing their rendered output:

   [plugin.myst]
   sembr = true
   

   Enable it per invocation with mdformat --sembr <filename>; --no-sembr overrides the TOML setting.

The facade also preserves established skip-formatting comments:

<!-- myform-ignore -->

This next block is left exactly as written.

<!-- myform-ignore-start -->

Every block in this range is preserved.

<!-- myform-ignore-end -->

<!-- myform-ignore-file -->

The markers act at the document top level. Their strings remain configurable through [plugin.myst].

Documentation

• Documentation front door
• API reference
• Universal translator specification
• Typst ecosystem memo
• Release procedure