MardoBlog

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:

  1. Spacing follows the mathematical role. The minus in -x has a different job from the minus in a-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.

  2. 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.

  3. 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 of an integral, the quadratic formula, and a rotation matrix rendered natively in Mardo
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 measureCountWhat we did
Public KaTeX issues in the September 20 snapshot1,687Classified every visible open and closed issue
Test files and fixtures in the pinned upstream tree408Inventoried upstream test directories
Identifiable upstream test cases or families1,040Recorded a decision for every entry
Test entries selected for translation43Selected parser or visual cases for Mardo checks
Font approaches considered5Compared design, font-data, and packaging tradeoffs
Expressions in the frozen visual corpus72Compared native output against the pinned reference at matched letter height
Supported expressions in that corpus71Retained 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.