Kuma

A tiny native Markdown-to-PDF renderer for macOS.

brew install subirats345/tap/kuma

Kuma is deliberately small: plain Markdown in, quiet A4 PDF out. It uses CoreText, ImageIO, and Quartz directly, so there is no browser, HTML layer, server runtime, or template engine involved.

The goal is not to support every Markdown extension. The goal is to make simple documents feel calm, native, and printable.

Install

With Homebrew:

brew install subirats345/tap/kuma

From source:

git clone https://github.com/subirats345/kuma.git
cd kuma
./Scripts/install-local.sh

Or build it manually:

swift build -c release
install -m 755 .build/release/kuma ~/.local/bin/kuma

Usage

kuma
kuma interactive
kuma input.md
kuma input.md output.pdf
kuma input.md -o output.pdf
kuma input.md --open

If no output path is provided, Kuma writes a .pdf next to the input Markdown file.

The short alias is installed as ku:

ku Examples/basic.md

Run Kuma without arguments for a small interactive flow. It lists Markdown files in the current folder, lets you choose an input, suggests the output PDF path, and asks whether to open or watch the result:

kuma

Create a starter Markdown file:

kuma init
kuma init notes.md

Watch a Markdown file and re-render the PDF whenever it changes:

kuma watch notes.md
kuma watch notes.md notes.pdf --open

Codex Skill

Kuma ships with a reusable Codex skill at skills/kuma-pdf. It tells an agent how to write Kuma-friendly Markdown, render the PDF, generate a first-page PNG preview, and check spacing, images, lists, and code blocks.

Install it into your local Codex skills folder:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R skills/kuma-pdf "${CODEX_HOME:-$HOME/.codex}/skills/"

Then invoke it from Codex:

Use $kuma-pdf to turn this Markdown note into a polished PDF and verify the preview.

Examples

The examples are intentionally made from public-domain texts, so the repository stays easy to share.

Source	Rendered PDF preview
Examples/basic.md
Examples/markdown-features.md
Examples/technical-note.md
Examples/moby-dick-loomings.md
Examples/shakespeare-sonnet-18.md
Examples/dickinson-hope.md
Examples/cervantes-quixote.md
Examples/aurelius-meditations.md

Render all examples locally:

Scripts/render-gallery.sh
open .build/gallery/index.html

Refresh the README screenshots from the same render pass:

Scripts/render-gallery.sh --update-screenshots

Markdown Support

Kuma currently supports the practical Markdown subset needed for calm documents:

• # through ###### headings
• paragraphs
• bold, italic, inline code, clickable PDF links, raw URLs, and emails
• blockquotes
• unordered, ordered, nested, and task lists
• simple tables
• horizontal rules
• local images with ![caption](path/to/image.png)
• fenced code blocks
• frontmatter blocks, which are ignored

Specialized extensions such as math, Mermaid diagrams, and raw HTML are intentionally outside the native renderer for now.

Development

swift build
swift test
swift run kuma Examples/basic.md .build/kuma-example.pdf
swift run kuma init .build/kuma-example.md
swift run kuma watch .build/kuma-example.md .build/kuma-example.pdf
Scripts/render-gallery.sh
swift build -c release

Kuma is dependency-free. The only requirement is macOS with SwiftPM.

Source layout:

• Sources/Kuma/ keeps the executable entrypoint tiny.
• Sources/KumaCore/MarkdownParser.swift turns Markdown into document blocks.
• Sources/KumaCore/InlineParser.swift handles inline emphasis, links, code, and escapes.
• Sources/KumaCore/PDFRenderer.swift draws the native PDF.
• Tests/KumaCoreTests/ protects the parser surface.