Markdown Gost

Why it exists.

I was bad at formatting documents to the standard and decided to automate it. I surveyed what already existed first, found nothing that covered what I needed and several projects too stale to build on, and only then started fresh. The repository was created in January 2025; I wrote my thesis between February and May of the same year — in Markdown, rendered by this converter. The thesis source opens with its list-marker and work-interval macros and uses the table-of-contents, figure-count, table-count and source-count macros throughout. I built a tool to solve my own problem, wrote an 88-page graded thesis with it, and then shipped it as a product.

The macro system.

Twenty-five pluggable macros, one module each: colour and highlighting, comments, automatic counts of figures, tables, formulas, sources and appendices, LaTeX formulas converted into real Word formula objects with variable glossaries, cross-references resolved in a second pass so a figure can be referenced before it exists, a macro that executes a Python file and embeds its standard output, Graphviz graph building, includes, listings, page breaks, bibliographies, document-wide variables, and list numbering that the converter does itself because the underlying library's numbering is unreliable.

Layered by responsibility.

A parser over marko; a document object model of runs, tables, lists, media and formulas that emits OOXML; the macro package; post-processors for heading numbering, internal links and sources derived from URLs; source converters including a dedicated arXiv adapter; and a render context carrying project settings.

It fails rather than lies.

An unnamed table raises instead of silently producing a document that does not meet the standard. For a tool whose entire value is compliance, a silent near-miss is the worst possible outcome.

Packaged, but not published.

It is a proper distribution — built with hatchling, versioned, installed like any other dependency — and it is deliberately not released to a public index. The site is how people use it.

Highlights

• Two-pass rendering, so forward references resolve
• Automatic numbering of every numbered entity: headings, figures, formulas, tables, appendices
• LaTeX → MathML → OOXML formula conversion through XSLT
• An optional cache for remote sources
• Fifteen or more real documents rendered, including work written on someone else's behalf and a law-faculty article

Stack

Python 3.12+python-docxmarkolxmlsympylatex2mathmlXSLTGraphvizPillowhatchling