v0.1.0

The first release of Amethyst: a CLI that turns a Markdown file into a
well-typeset PDF or Word document. One file in, one styled document out —
no flags required, no stylesheet to write, no reference .docx to maintain.

uv tool install amethyst-cli
amethyst convert notes.md -o notes.pdf
amethyst convert notes.md -f docx

PDF output additionally needs Pango, which is a system library:
brew install pango on macOS, or
apt install libpango-1.0-0 libpangoft2-1.0-0 libharfbuzz-subset0 on
Debian and Ubuntu. DOCX output needs nothing beyond the wheel.

The full documentation covers every option, the
theme format, the configuration layers and the architecture.

What it does

Both formats come out of one theme, so the same source reads as the same
document in either. That covers headings, bold, italic, strikethrough,
inline code, hard breaks, nested and ordered lists, task lists,
blockquotes, GFM tables, horizontal rules, links, local and remote images,
fenced code with syntax highlighting, and footnotes — plus the furniture
around them: a table of contents, page numbers, a running head that tracks
the current section, a title page built from the frontmatter, and document
metadata. PDFs also get nested outline bookmarks straight from the
headings.

Three themes ship: default, academic and github. A theme is one TOML
file declaring fonts, a type scale, colours, spacing and page geometry,
and it compiles two ways — to CSS custom properties for the PDF and to
Word style definitions for the DOCX. Start from a builtin and change what
you want:

amethyst themes show default > house.toml
amethyst convert report.md -f pdf -t house.toml

Settings resolve from builtin defaults, then ~/.config/amethyst/config.toml,
then ./amethyst.toml, then the document's own frontmatter, then the flags
you typed. amethyst init writes a starter config with every setting listed
and commented out.

Remote images are downloaded once, before rendering starts, and cached.
--no-remote turns that off. Exit codes are distinct so the tool composes
in scripts: 0 ok, 1 conversion failure, 2 bad usage, 3 a missing system
dependency.

Known limits

• Footnotes in Word are an endnote-style list at the end of the
  document, not real Word footnotes.
• Task lists in Word are printed ☐ / ☑ glyphs rather than clickable
  checkboxes.
• Raw HTML passes through to PDF and is skipped in DOCX, with one
  warning naming the line it was on.
• A data: image URI embeds in PDF but is skipped in Word.
• The output format must be stated, by -f, by an output path ending
  in .pdf or .docx, or once in a config file.
• LaTeX math and Mermaid diagrams are out of scope for now.

Requires Python 3.10 or newer; tested on 3.10 through 3.13.