Mathematics should look like mathematics
Mardo 1.1.0 · · Adam and Truly Floof
Edmund Harriss tried Mardo and sent us some working mathematical notes. We ended up scouring 1,687 public KaTeX issues and cataloguing 1,040 identifiable test cases and families from an inventory of 408 test files and fixtures to improve how that mathematics reads.
We went all in on the research! Mathematics has had a long time to accumulate ways of being slightly wrong on a page, and there was a tremendous amount to learn from people who had already found them.
Mardo is our native Markdown editor for the Mac, built on MarkEngineV3. Mathematical notes are exactly the sort of work we want it to make comfortable. A variable should read as a variable, an integral's limits should belong to its sign, and a matrix should fit inside its brackets. When someone is thinking through an idea, the typography should help them stay with it.
Edmund's examples gave us whole pages of real work to judge. Looking across those pages, we could see awkward integral limits, undersized matrix brackets, and variables that looked too much like ordinary text. We wanted to understand the rules behind those relationships well enough to improve the whole page.
We scoured the mathematical typography record
We investigated TeX layout, mathematical rendering libraries, and fonts. KaTeX became our main visual reference because it provided both familiar mathematical typography and a substantial public record of things that had gone wrong.
Our frozen September 20 snapshot covered public issues stretching from 2013 to 2026. Every one of the 1,687 visible public issues, open and closed, received a classification. Every one of the 1,040 identified test cases or families received a decision. We followed the record through layout rules, font measurements, and the fixes linked from those reports. That archive contains years of mathematical typesetting experience, generously made available by the KaTeX contributors and users.
The work produced 43 test entries selected for translation into Mardo checks. Other entries supplied reference behavior, duplicated an existing case, or covered capabilities beyond the current renderer. The issue and test counts measure the research audit; the execution counts appear below with the checks we actually ran.
For repeated visual comparisons, we froze 72 expressions covering algebra, calculus, linear algebra, probability, number theory, logic, geometry, and physics. They exercise scripts, fractions, roots, accents, operators, matrices, cases, and combinations of those pieces. We compared at matched measured letter height, so a larger rendering could not win by being larger.
Mardo currently supports 71 of those 72 expressions. The remaining example uses \mid, which stays visible as source. It remains in the corpus so the reported total includes the unsupported case.
Three ideas from Donald Knuth
Edmund also told me to look at Donald Knuth's work as foundational reading in mathematical typography. The TeXbook, particularly Chapter 17 and Appendix G, rewards the attention. Knuth documented TeX, METAFONT, and Computer Modern in five volumes that explain how to produce their own printed appearance. Even the books are showing off.
Three details are easy to miss once a formula looks recognisable, and we use all of them in Mardo:
Spacing follows the mathematical role. The minus in
-xhas a different job from the minus ina-x. Knuth's eight atom classes give the renderer a vocabulary for those relationships, with context deciding when an apparent binary operator is actually ordinary. Mardo carries these roles through nested expressions and applies one shared spacing table, so the same mathematical relationships survive the trip from the editor to Finder preview and PDF.Nested mathematics needs eight layout styles. TeX has display, text, script, and scriptscript styles, each with a cramped variant. The cramped versions lower superscripts, which matters inside roots and fraction denominators. Mardo carries all eight states through its shared layout. A superscript under a root can sit lower while its letters keep the same size. Simply shrinking a completed formula would miss that relationship.
Scripts follow the shape of the letter. An italic letter can lean beyond the width allocated to it. Knuth's script-placement rules account for that lean with an italic correction: the upper script can move farther right while the lower script keeps a different attachment. Mardo reads Asana's modern OpenType MATH measurements and applies that asymmetry in the native layout. In something as small as
f_i^2, the font's geometry gets a say in where both scripts belong.
Five font approaches, one mathematical face
Correct spacing still left a visible difference in the shapes of letters, operators, and delimiters. We considered five font approaches: keeping the system STIX face, bundling KaTeX's split fonts, bundling New Computer Modern Math, constructing a face from KaTeX outlines, and bundling Asana Math unchanged. Those were five design and packaging approaches, with different costs for font selection, metrics, licensing review, and portability.
We chose Asana Math for its conventional mathematical typography and built-in layout metrics, which work directly with Mardo's native renderer and keep the font data consistent across installations.
Mardo bundles the exact Asana Math 000.962 font and its notice. Together they add 442,566 bytes per bundle, about 443 KB of passive font data and documentation. Mathematical italics, upright symbols, large operators, and growing delimiters come from that one face.
A mathematical font contains more than outlines. Its OpenType MATH table supplies measurements for script placement, fraction gaps, accents, radicals, and enlarged symbols. Mardo still has to compose the expression correctly; the table gives it measurements appropriate to the font.

Original examples rendered by Mardo's native renderer with the bundled Asana Math font.
One correction has to work everywhere
An integral and a sum place their limits differently. Display sums put them above and below. Integrals normally keep them at the sides, near the corners of the tall sign. Scripts must follow those relationships when another expression is nested inside them.
Matrices need enough room between rows, and their delimiters need to enclose the complete grid. An indexed root needs a legible degree, a sign that fits its contents, and an overbar that actually meets the sign.
The broad reading page caught problems that isolated examples had missed. One inherited positioning rule left a radical's bar hanging to the left of its corner. The fix was to remove that rule and use the font's sign advance as the shared join. We added a geometry regression for it.
That became the working rhythm: find the shared relationship, add a failing check, correct it, and look again at the complete page.
The native math proof also renders 513 distinct bounded formulas and exercises 2,000 cached paints, checking cache limits and retained allocation growth as it goes. Repeated painting matters because this is an editor: the same mathematics gets drawn again as someone scrolls and types around it.
Edmund's follow-up also helped us refine the spacing around the “such that” colon in set notation.
The exported page counts too
Preparing examples for Edmund also brought the exported page into the work. Wide equations need to fit a portrait PDF's printable column, long metadata values need to wrap, and invisible closing rows should leave the final page alone.
The new PDF checks exercise long mathematics, Unicode metadata, printable margins, and 18 pairs of documents at different lengths around page boundaries. Each pair checks the effect of a concealed closing marker. Both supplied mathematical notes now export as complete three-page portrait PDFs, with their original source files unchanged.
The earlier October 27 integration had already exercised 52 PDF fixtures totaling 2,654 pages. The follow-up adds the focused checks above for these particular mathematical notes. Both the broad corpus and the small, specific regressions belong in the account of the work.
The research and verification numbers
The research was extensive, and the numbers deserve to be easy to find. Each row names what was counted.
| Research measure | Count | What we did |
|---|---|---|
| Public KaTeX issues in the September 20 snapshot | 1,687 | Classified every visible open and closed issue |
| Test files and fixtures in the pinned upstream tree | 408 | Inventoried upstream test directories |
| Identifiable upstream test cases or families | 1,040 | Recorded a decision for every entry |
| Test entries selected for translation | 43 | Selected parser or visual cases for Mardo checks |
| Font approaches considered | 5 | Compared design, font-data, and packaging tradeoffs |
| Expressions in the frozen visual corpus | 72 | Compared native output against the pinned reference at matched letter height |
| Supported expressions in that corpus | 71 | Retained the unsupported \mid case in the reported total |
During the November 1 integration qualification, the whole-product candidate passed 333 portable tests, 1,102 app-smoke checks, and all 22 standard release gates. The math proof, colon comparisons, and focused PDF regressions described above supply the evidence specific to this work.
How we measured
The issue and test census comes from the frozen September 20 research snapshot, with KaTeX source pinned at 726c2d4e43e8fb0890da19de086893759b1a0936. The visual reference uses KaTeX 0.18.7; comparisons match measured italic-x height. Counts distinguish inventoried upstream cases, selected translations, supported visual examples, and executed Mardo checks.
The November 1 release qualification ran on a MacBook Air with an Apple M4 and 32 GB of memory, macOS 15.7.4 (24G517), Xcode 26.1.1, and Swift 6.2.1. That candidate was 0dde7b9, with math renderer 17. The 52-fixture, 2,654-page PDF total belongs to the October 27 integration; the later PDF work has its own focused regression results.
What this update is for
The aim is comfortable mathematical notes in ordinary Markdown files. Mardo keeps its own bounded native renderer, with one parser, one layout mechanism, and one drawing plan shared across the app, Finder previews, and PDF. KaTeX remains a research reference.
Full LaTeX papers still have their own publication workflow. Mardo's current math support is a defined subset, and an MDX page's interactive components still need their website environment.
We are also working on an extension system that keeps Mardo's engine solid while allowing extensions to support the interactive work discussed in that conversation. That work is in progress and is separate from these typography improvements.
These improvements are part of Mardo 1.1.0. Thank you, Edmund, for bringing real mathematical work to Mardo and taking the time to explain what would make it comfortable to use. We want you to be able to stay with the mathematics.
About Mardo. Mardo is a native Mac app for reading and editing Markdown, made by Floof Logic and built on MarkEngineV3, its own Markdown engine, with no web view inside. It launches faster than Apple's own text view, and it opens a 50 GiB file ready to edit in about an eighth of a second. When an AI agent or another app saves the file you have open, Mardo adopts the new version in place, merges it under your unsaved edits when the two don't overlap, and keeps your place; Timewarp lets you step back through the file's past versions while it's open. Claude Code, Codex, ChatGPT and Claude Desktop can open a file in Mardo at the exact lines that matter, over a local MCP connection with no network port. Press Space on any Markdown file in Finder for a rendered Quick Look preview.
Reading, Quick Look, Find, Outline, Print, Follow Live Edits and Timewarp are free, with no time limit and no account. Mardo Pro adds editing and export for US $29.99, paid once, after a trial of 14 days of use that starts the first time you open Mardo. Documents never leave your Mac. Mardo runs on macOS 14 or later, on Apple silicon and Intel. Download it from mardo.app, or install it with brew install --cask flooflogic/tap/mardo.
Every Mardo release · Star Mardo on GitHub · Written in Markdown. Exported by Mardo. Good for no reason.