RayoMD is a tiny native Markdown-to-PDF converter built for fast startup, small releases, and predictable deployment.
The default renderer parses Markdown and writes PDF bytes directly from C++17. It does not start a browser, bundle a runtime, or require Pandoc or LaTeX. Windows ships a compact Dear ImGui app with CLI modes; Linux uses the same native exporter through a small CLI.
- Native PDF generation with no browser engine on the fast path.
- A single Windows GUI executable and a compact Linux CLI.
- Bounded parallel batch conversion, stdin, warm serve, and benchmark modes.
- Unicode, clickable links (also bare URLs), bookmarks, tables, task lists, GitHub alerts, footnotes (as on GitHub, at the end of the text), code highlighted as on GitHub in 29 languages and formats, local images (also SVG, drawn as vectors), and opt-in URL images.
- Natively typeset math for a TeX subset: no LaTeX, no browser, no embedded math fonts.
- Optional exact Markdown recovery through reversible PDFs.
- Tables of contents (
[TOC]or--toc) with dot leaders, page numbers and links to the headings. - Books (
--book): one PDF of the files aSUMMARY.md(mdBook, GitBook) or a folder lists, each from a new page, with the links between them, one outline and one table of contents. - Optional compression (
--compress) with a built-in DEFLATE encoder: text-heavy PDFs come out two to five times smaller. - Company themes (
--theme=FILE): your TrueType font, colours, header and footer text with a logo, and a cover page. - PDF/A-3b archives (
--pdfa): every font embedded, sRGB output intent and XMP metadata; formulas show their TeX source. - Optional Windows Pandoc mode when the native subset is not enough.
Use native RayoMD for simple reports and bulk conversion when startup time, package size, and dependency count matter. Use Pandoc, a browser renderer, or LaTeX when you need full CommonMark/Pandoc extensions, complete LaTeX math, filters, templates, citations, highlighting for every language, or HTML/CSS fidelity.
On 2026-07-18, order-balanced tests measured RayoMD 2.6 against the repository's
tester.md with and without image syntax:
| Platform/storage | Warm: imageless | Warm: image-bearing | Fresh process: imageless | Fresh process: image-bearing |
|---|---|---|---|---|
| Windows 11 workspace | 0.447 ms |
0.714 ms |
21.10 ms |
98.39 ms |
Linux WSL /mnt/e |
0.225 ms |
5.120 ms |
25.45 ms |
153.63 ms |
A fresh process includes startup, source reading, PDF generation, output
writing, and exit. The existing Python runner measured 32 A/B pairs after six
preflights per case; filesystem and OS caches may remain warm. Even with the
image-bearing fixture, the median stayed below 100 ms on Windows and below
160 ms on WSL's Windows-mounted workspace.
Warm --bench medians exclude startup, input reading, and timed output writing.
They use 10 A/B pairs (1,000 builds per Windows round and 200 per WSL
round). The image-bearing fixture reuses the local mascot; URL fetching stayed
off, so remote and missing sources used deterministic fallbacks. Every repeated
PDF was byte-identical within its platform and case.
The WSL result includes /mnt/e path and file-access costs and is not a
Linux-native/ext4 claim.
See the 2.6 performance snapshot for p95 values, ranges, hashes, fixture details, and reproduction commands. The benchmark index keeps cross-tool, warm-path, reversible-PDF, and older release reports organized.
On 2026-10-09, warm --bench builds of the 3.1.0 Linux release against 3.0.0 (the
same DejaVu Sans font, 11 CPU-pinned rounds of the nine watch-suite documents) ran
about 1 % faster overall: Unicode documents up to 9 % faster, ASCII documents 7 % to
17 % slower because they now draw bold and italic faces, formatted table cells with
links, and a bookmark for each heading. performance.md
records what each change cost.
Download a package from Releases, or build from source.
Windows:
cmake -S . -B build/windows -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release
cmake --build build/windows --config Release
build/windows/rayomd.exeLinux/WSL:
cmake -S . -B build/linux -DCMAKE_BUILD_TYPE=Release
cmake --build build/linux --config Release
./build/linux/rayomd --doctor
./build/linux/rayomd --export input.md output.pdfCommon CLI workflows:
rayomd --export input.md output.pdf
rayomd --batch input-folder output-folder --recursive --skip-unchanged --report=report.jsonl --workers=8
rayomd --export input.md reversible.pdf native elegant normal --embed-source
rayomd --export input.md numbered.pdf --page-numbers --page-size=letter
rayomd --export input.md small.pdf --compress
rayomd --export input.md branded.pdf --theme=acme.theme
rayomd --export input.md archive.pdf --pdfa
rayomd --book docs/SUMMARY.md manual.pdf --toc
rayomd --recover-source reversible.pdf recovered.mdThe Windows app supports editing, drag-and-drop, engine/style/margin selection,
URL-image opt-in, reversible-PDF inspection, and Ctrl+E export.
For dependencies, curl-enabled Linux builds, stdin/serve modes, security flags, exit codes, and all options, use the Getting Started and CLI Reference.
| Topic | Guide |
|---|---|
| Installation and builds | Getting Started |
| Commands, flags, and exit codes | CLI Reference |
| Supported Markdown subset | Native Markdown Support |
| Exact source recovery and privacy | Reversible PDFs |
| Embedding the exporter | C++ API |
| Benchmarks and caveats | Benchmarks |
| Regression measurement | Performance Watcher |
| Contributing | CONTRIBUTING.md |
Version-specific engineering contracts remain beside the code:
docs/development/reversible_pdf_profile.mddocs/development/native_math.mddocs/development/performance.mddocs/development/arbitrary_pdf_research_decision.md
Native mode supports ATX and Setext headings (as PDF bookmarks and as targets of
GitHub-style #anchor links; a heading never ends a page), paragraphs, structured
nested lists (with GitHub task lists), block quotes and GitHub alerts (> [!NOTE]
and the other four), fenced and indented code (fenced code in a language GitHub knows in
its colours, --no-highlight to keep it one colour), footnotes, pipe tables (whose header row repeats
on every page), rules, page breaks, matching-run code spans, classic emphasis and
escapes, inline and reference-style links, URL/email autolinks (in angle brackets or
bare, as on GitHub), standalone inline/reference images (PNG, JPEG, and SVG drawn as
vectors with their text in the document's font),
natively typeset math for a TeX subset ($...$, $$...$$, fenced math blocks, in
text, lists, quotes, headings and table cells), Unicode fonts (or the PDF standard
fonts when no system font is found), HTML comments (hidden), <br> line breaks,
character references such as ©, PDF metadata from the front matter (title,
else the first heading; author, subject, keywords and language), opt-in page numbers,
a table of contents at a [TOC] or [[_TOC_]] paragraph or with --toc, books of
several files (--book), and common status-symbol normalization.
Images embedded in paragraph text use a consistent image: alt fallback;
standalone images retain native image layout and missing-image fallback text.
It deliberately does not promise full CommonMark/Pandoc compatibility, complete LaTeX math (packages, macros, automatic numbering), highlighting for every language, citations, filters, templates, right-to-left scripts (Arabic and Hebrew are drawn left to right, unshaped), complete SVG (filters, masks, radial gradients, patterns, markers, and HTML or scripts in SVG are not drawn as a browser draws them; an SVG that needs HTML, scripts or style sheets it cannot match shows its alt text), or HTML/CSS layout fidelity. The complete and current matrix is maintained in Native Markdown Support.
Default releases remain dependency-light; see Packaging and Releases for the full release policy:
rayomd-<version>-windows-x64.zip— Windows GUI and CLI executable.rayomd-<version>-linux-x64.tar.gz— portable Linux CLI without libcurl.rayomd-<version>-linux-x64-curl.tar.gz— Linux CLI with URL-image support.
Do not bundle Pandoc into the lightweight package. It is an optional external compatibility path with separate licensing and deployment considerations.
Before contributing, read AGENTS.md and
CONTRIBUTING.md. Keep benchmark claims dated and scoped,
and keep generated builds, PDFs, corpora, and raw reports out of source.
RayoMD is released under the Apache License 2.0. See LICENSE and
NOTICE. Dear ImGui retains its own license in
third_party/imgui/LICENSE.txt.