Markdownthat arrivestypeset.

One command turns a Markdown file into a PDF and a Word document that share a single theme. No stylesheet to write, no reference .docx to keep in sync.

Scroll

Everything it takes to run it

Two commands, one system library, and a clear message when it is missing.

Runtime
Python 3.10 or newer
Package
amethyst-cli
Command
amethyst
Licence
MIT
$ uv tool install amethyst-cli# or: pip install amethyst-cli$ amethyst convert notes.md -o notes.pdf$ amethyst convert notes.md -f docx

The format comes from -f, or from an -o path ending .pdf or .docx.

PDF output needs Pango, a system library, and the only thing here you install outside Python. DOCX needs nothing at all — and without Pango, -f docx still works while -f pdf exits 3 with a message naming exactly what to install.

macOS
brew install pango
Debian
apt install libpango-1.0-0 libpangoft2-1.0-0 libharfbuzz-subset0

The full install guide

One theme file, two renderers

Why the PDF and the Word file read as the same document.

A theme is a single TOML file. It compiles to CSS custom properties for the PDF and to Word styles for the DOCX. Anything it leaves unset falls back to default.

  • default
  • academic
  • github

default is serif with a violet accent, and the fallback for anything another theme leaves unset. For the other two, run amethyst themes show github and read the file — this page will not paraphrase something you can check in a second. amethyst init writes you one to edit.

What it sets, and what it won't

The complete list, limits included.

Rendered in both formats

PDFs also get nested outline bookmarks built from the headings.

  • Headings
  • Bold, italic, strikethrough
  • Inline code
  • Hard breaks
  • Nested and ordered lists
  • Task lists
  • Horizontal rules
  • Links
  • Local and remote images
  • Fenced code, syntax highlighted
  • Footnotes
  • Table of contents
  • Page numbers and running head
  • Title page and metadata

Four things it does differently

None of these is a bug report.

  • Word footnotes are an endnote-style list

    Not Word's own footnote field. The PDF gets real footnotes.

  • Word task lists are ☐ and ☑ glyphs

    Characters in a paragraph, not checkbox controls you can tick.

  • Raw HTML reaches the PDF only

    It is skipped entirely in DOCX rather than approximated.

  • LaTeX math and Mermaid are out of scope

    Not planned, not half-working. Reach for another tool.

How a run is decided, and how it ends

Five config layers, four exit codes.

Where a setting comes from

Later wins. A flag beats everything.

  1. 1Builtin defaults
  2. 2~/.config/amethyst/config.toml
  3. 3./amethyst.toml
  4. 4Frontmatter
  5. 5CLI flags

Exit codes

Scriptable, and documented.

Exit codes returned by the amethyst command
CodeMeaning
0Converted
1Conversion failed
2Bad usage
3Missing system dependency

It opens a socket in exactly one place

Downloading remote images. That is the entire list.

Images your document links to by URL are fetched once and cached in ~/.cache/amethyst/images. Pass --no-remote and even that stops, at which point conversion is entirely local. Nothing about a document, its contents, or its use is sent anywhere.

Read the full flag referenceWhat this site collects