Markio

A native macOS Markdown viewer with no web view, no HTML and no JavaScript.

Every glyph on screen is typeset by CoreText from a parser that reads the file's bytes directly. Nothing is converted to HTML on the way, so there is no browser engine to start, no document object model to build, and no second copy of the text living inside a renderer. The point of that is what it buys on large files: an 8 MB document opens as fast as an 8 KB one, and scrolling through a 32 MB one measures the same as scrolling through a short note.

Markio reads. It never writes a file it opens.

What it renders

• CommonMark blocks: ATX and setext headings, paragraphs, nested block quotes, bullet and ordered lists (tight and loose, nested), fenced and indented code, thematic breaks
• GitHub extensions: tables with per-column alignment, task lists, strikethrough, autolinks — including the bare ones nobody marked up, so a https://…, a www.… and an email address in the prose are all links
• Tables written with HTML tags, merged cells included — the one thing Markdown's own table syntax cannot express
• YAML front matter, shown as a highlighted metadata block
• Inline: emphasis, strong, code spans, links (inline, reference, autolink), entities, hard and soft breaks
• The inline HTML that carries meaning — <b>, <em>, <kbd>, <mark>, <u>, <del>, <code>, <sup>, <sub>, <br> and their synonyms — mapped straight to text styles. There is no HTML engine; anything else is dropped rather than shown
• Formulas between dollars, set with real glyphs: Greek, scripts, stacked fractions, roots, accents, the blackboard and script alphabets, matrices, cases and aligned, and a display formula's limits above and below its sum sign. What the subset does not cover keeps its source rather than being guessed at
• Syntax highlighting for Swift, Python, Go, Rust, shell, SQL, JSON, YAML and the C family, in light and dark
• A pasted terminal log in its own colours: the sixteen basic colours, the 256-colour cube and true colour; a ```diff block as added and removed bands
• Images beside the document, decoded at the size they are drawn — on a line of their own, or inside a sentence
• Footnotes: a raised label in the text, the note itself set smaller below
• <details> sections, folded away until you click their summary
• Mermaid flowcharts — every shape, all four directions, subgraphs in their own frames, classDef colours — and sequence diagrams with loops, alternatives, notes and activation bars, plus pie charts, state machines, class diagrams, entity–relationship diagrams, mindmaps, timelines, user journeys, Gantt charts, quadrant charts, xy charts, git graphs, packet diagrams, kanban boards, requirement diagrams, Sankey diagrams, treemaps, C4 diagrams, architecture diagrams, radar charts, block diagrams and ZenUML, drawn with paths and glyphs, each showing the title its YAML preamble gave it. No web view, no diagram library. What the subset does not cover stays a fenced block

Reading it

• ⌘O open, ⌘⇧O open the document in your editor (Markio ▸ Editor picks which; the default is the next app registered for the file, never Markio itself), ⌘W close, ⌥⌘W close every window, ⌘⇧C copy the document's path
• ⌘F find, ⌘G / ⌘⇧G next and previous match
• ⌥⌘S the table of contents — the heading tree, click to jump, with each section's ticked-of-total beside it and its task items listed underneath, one line each, the ticked ones struck through
• ⌥⌘J / ⌥⇧⌘J next and previous open task box, also on the arrows beside the count in the bottom bar
• ⌥⌘M the map down the right edge: the document itself, drawn small — every line as the words on it, at the column they start on, tinted by what the block is, with the find matches, the blocks a comparison changed, the open task boxes, and a rectangle showing where you are. On a document longer than the map, it shows a window onto the text and slides it with you. Click to go there, drag to scroll, hover to see which section it is
• ⌥⌘Z zen: the document and nothing else — no outline, no map, no bottom bar, an empty title bar, and the window takes the display, which hides that too. Escape leaves it, and the window comes back showing exactly what it showed before
• ⌥⌘P presentation: the document a screenful at a time, split where the author split it — on their thematic breaks, or failing that on their headings
• ⇧⌘E export as PDF, ⌘P print — real glyphs and vector diagrams, not a picture of the window
• ⌘+ / ⌘− reading column width, also on the slider in the bottom bar
• Select text with the mouse, ⌘A select all, ⌘C copy — with its styles where they are wanted, and as plain text everywhere else
• Click a link to open it; light and dark follow the system
• Drop a Markdown file on a window to open it
• A file path a report names — Sources/Markio/main.swift:42 — is a link when the file is really there, and opens at that line in the same editor
• Click a table's header to sort by it, again to reverse it, and a third time to get the author's order back; type in its filter row to keep the rows that match. The header stays put while the rows scroll, and the file is never touched
• The bottom bar says what the document says about itself: how many of its boxes are ticked, how long it takes to read, how many open questions it still carries. A ticked box's text is struck through; click the count, or its arrows, to go to the next box that is still open

Building it

Needs Deno 2 and a Swift 6.3 toolchain.

deno task check

That is the gate: format, lint, type-check, a debug build and a release one, a scan for TODO markers, a scan that fails if WebKit or JavaScriptCore ever appear in the sources, a format lint, and the tests. Both configurations are built because the release compiler sees across files and rejects captures the debug one accepts, and the release build is what a reader ends up running.

Other verbs:

• deno task app — build the .app bundle into .build/Markio.app
• deno task dev <file.md> — build and open a document
• deno task test — the test suite alone
• deno task bench — parse cost and memory footprint at 1, 8 and 32 MB
• deno task viewbench — what one document costs the Mac apps that open it, this one and any other, measured from the outside (the procedure)
• deno task layoutbench — crossings, lines through boxes, covered words and detours in how the graphs in test-fixtures/layout/ are laid out
• deno task icons — redraw the app icon set from Icon.swift
• deno task dist — the unsigned bundle; signing and upload happen outside this repository

The app can draw its own window into a PNG, which is how rendering is checked without a screen:

.build/Markio.app/Contents/MacOS/Markio doc.md --capture=/tmp/shot.png

Add --capture-hover=<x>,<y> to park the pointer first, for the controls that only appear under it, --capture-click=<x>,<y> for what only a click shows, --capture-type=<text> to type into whatever that click focused, or --capture-scroll=<points> for what only appears once a document has been scrolled. --compare=<path> (with --side-by-side) captures a comparison without a hand on the mouse, --present [--slide=<n>] opens the deck, --export-pdf=<path> writes the PDF and quits, and --dump-menu[=<path>] writes the menu bar as AppKit has it — every item with its shortcut, whether it is enabled, and which object would receive it. It waits 2.5 seconds first and says in its first line whether the app was active and which window was key: an inactive app disables every document command, so a dump that says active=false cannot answer whether an item is enabled. Add -ApplePersistenceIgnoreState YES when the shot must show one document and not whatever macOS restored alongside it. The bench harness renders offscreen, and takes a baseline when the thing to look at is a comparison:

.build/release/markio-bench snapshot new.md /tmp/diff.png 900 620 light 0 old.md

What it costs

Release build, Apple silicon, generated documents of realistic shape:

• 1 MB — parse 1.9 ms (520 MB/s), 10 436 blocks, structure 0.4 MB, first viewport 0.4 ms
• 8 MB — parse 14.7 ms (545 MB/s), 84 725 blocks, structure 3.0 MB, first viewport 0.3 ms
• 32 MB — parse 69.3 ms (462 MB/s), 341 868 blocks, structure 12.2 MB, first viewport 0.3 ms

Peak resident memory across all three: 73.6 MB. The parse tree costs 38% of the file it describes, and the time to the first screenful does not grow with the document, because only the blocks on screen are ever typeset.

Layout

• Sources/MarkdownKit — the parser. Pure Swift, no AppKit, byte-level
• Sources/MarkioRender — CoreText typesetting, the virtualized layout and the reading view
• Sources/Markio — the app: documents, windows, menus, live reload
• Sources/MarkioQuickLook — the Finder preview extension
• Sources/markio-bench — headless measurement and offscreen rendering
• documents/ — requirements, design and per-task notes