Archival and Accessible PDFs

Archival and Accessible PDFs

(since 3.2) Two opt-in modes write PDFs that standards validators accept. Both embed every font, so they need a TrueType or OpenType font (.ttf, .otf or .ttc): a system font, or one named by RAYOMD_FONT; without one the export fails with exit code 18. Formulas are set in embedded fonts, so --pdfa typesets them (since 4.5; before, it showed their TeX source); --pdfua still shows formulas as their TeX source.

rayomd --export report.md archive.pdf --pdfa
rayomd --export report.md accessible.pdf --pdfua
rayomd --export report.md both.pdf --pdfa --pdfua

PDF/A-3b (--pdfa)

PDF/A-3b (ISO 19005-3, level B) for long-term archiving: every font embedded (page numbers in the document's font too), an sRGB output intent, XMP metadata that tells what the document information does (title, author, subject, keywords), a file identifier, and printable link annotations. With --embed-source the file stays PDF 1.7, as PDF/A-3 allows the attached Markdown. Checked with veraPDF (verapdf -f 3b).

PDF/UA-1 (--pdfua)

Tagged PDF/UA-1 (ISO 14289-1) for screen readers and other assistive technology. Besides the fonts and formulas above, it adds a structure tree in reading order:

Markdown	Tagged as
Headings	H1 to H6, never more than one level below the previous one (a document that starts at ## starts at H1)
Paragraphs	P
Lists	L, LI, Lbl (the bullet or number) and LBody; nested lists inside their item; a task's checkbox is its label, read as ☐ or ☑. (since 4.5) A drawn bullet is the label, with ActualText •, ◦ or ▪ by depth, and its list has /ListNumbering /Disc, /Circle or /Square
Block quotes, alerts	BlockQuote; an alert is a Div whose title is its first paragraph
Code blocks	Code
Tables	Table with THead and TBody, TR, TH (scope: column) and TD
Images	Figure with the alt text; an image without alt text is decoration
Display formulas	Formula with its TeX source as alternate text
Links	Link around the link text (or a linked image), joined to its annotation, whose description is that text
Footnotes	Reference around each mark and a Note for each note
Table of contents	TOC with a Caption and a TOCI per entry

Code tints, quote bars, rules, table borders, the footnote separator, a table header row repeated on a new page, headers, footers, page numbers, a theme's cover page and the table of contents' dots and page numbers are marked as artifacts, which assistive technology skips. Bold text is drawn once, so it is read once.

The document's language is the front matter's lang, else en; its title is the front matter's title, else the first heading, else the file name, and viewers show it in their title bar. With --pdfa too, the file claims both standards and its metadata declares the PDF/UA identification to PDF/A. With --embed-source it stays PDF 1.7.

veraPDF (verapdf -f ua1) checks the machine-checkable rules of PDF/UA; it passes all of RayoMD's test documents. What only a person can judge stays with the author: meaningful alt text, link text that makes sense out of context, and a sensible heading outline.

Cost

Tagging adds a structure element for every paragraph, list item part, table cell and link. Measured on 2026-10-09 against --pdfa (warm --bench, Linux, native storage):

Document	--pdfa	--pdfua	Size
96 KiB of ASCII prose	2.11 ms	3.22 ms	923 → 1,502 KB
96 KiB of tables	2.20 ms	4.59 ms	1,112 → 1,810 KB
kubernetes documentation	9.24 ms	11.16 ms	2,748 → 3,639 KB
fastapi documentation	22.01 ms	37.67 ms	6,425 → 10,823 KB

Ordinary exports are unaffected: without these flags the PDF bytes stay as they are.