← Back

MD Render

A workspace that treats a .md file as a document to read, with the typographic control that makes long-form reading comfortable.

Project overview

Type: Product · 6-week 0→1 · cross-device web app
Project type: 0→1 · Reading & Writing Tool · Markdown & Documents · Legibility
Role: Lead Product Designer · Reading & Typography UX · UX Research · Experiment Design
Methods: Comparative reading study · usability testing (SEQ) · A/B
Tools: Otter.ai · Maze · Figma + Dev Mode · Amplitude · Statsig
Case thesis: Designing a workspace that reads a .md file as a document, with the typographic control of a real reader plus light organization and editing, so people can use markdown the way they now use Word and PDF.

The context

Markdown became the common format for giving context to AI, and that pushed it into everyday use: people now receive and produce long .md documents the way they would a Word file or a PDF. Most tools that handle .md still treat it as code, in plain-text and code editors built for syntax rather than reading, or as notes, in apps like Obsidian that frame a file as one node in a second-brain library. A newer crop of lightweight markdown viewers has begun to target reading AI output specifically, which confirms the need is real — but they tend to be thin on typographic control and mostly desktop-bound. The format people now read at length still lacks a reading-first home with the depth of control long-form reading takes.

The problem

Reading a long .md is fatiguing, so people leave the format to read it. In research, 58% read long markdown in a code or plain-text editor, where monospace type and raw layout make sustained reading hard, and 44% had converted a .md into another format (pasting it into a doc or exporting a PDF) just to read it comfortably (behavioral, self-report). Reading a long .md past its halfway point happened only 38% of the time in a code-editor view (behavioral, reading test). The format the AI era runs on is awkward for a human to read.

The goal

Make a .md comfortable to read, edit, and organize as a document, measured by long-read completion, the workaround of converting md to read it, and retention, rather than by how many markdown features the tool supported.

Empathize — People now read long .md documents in code editors, and 44% had converted one to another format just to read it

In this section: Research foundation · Key insights

Research foundation (method)

Phase 1 — Interviews (n=20, ~35 min, frequent markdown users including non-developers, recruited via dscout, transcribed in Otter.ai): how they read, write, and store .md today.
Phase 2 — Comparative reading study / reading test (n=26): participants read a long .md in their usual tool while we recorded how far they got and rated comfort.
Phase 3 — Survey: ~1,006 invited; 180 analyzable responses (17.9% response rate); ~124 completed every item (12.3% completion rate). Attitudinal percentages are computed on the 180 analyzable responses; question types are labeled per question in the appendix.
Phase 4 — Usability testing (SEQ): task-based sessions on the reader and editor, with a Single Ease Question after each task, which surfaced the typographic settings readers reached for.
Phase 5 — Prototype pilot (Amplitude-instrumented, 65 users, ~32 per A/B arm, spring 2025): reading and editing behavior on the reader and editor.

Key insights

1. Markdown is now a document people read at length, in tools built for code. The .md files people received from AI and shared as specs and reports were long-form reading, but they opened in code editors where reading was uncomfortable. Triangulation:

Behavioral: 58% read long markdown in a code or plain-text editor; long-read completion there was 38%.
Verbatim (P9, PM, non-developer) — coded: Wrong tool for reading: "It's a five-page document, but it opens like source code, so I can't actually sit and read it."

2. To read a long .md, people leave the format. Rather than read it in place, users converted markdown into a doc or PDF to get a readable layout, which lost the editability and the markdown source they needed for AI.

Behavioral: 44% had converted a .md to another format purely to read it.
Verbatim (P14, researcher) — coded: Convert-to-read: "I paste it into Google Docs just so I can read it, and then I've got two versions and the markdown one is the one the AI actually needs."

3. The existing markdown homes impose a system people did not want. Note apps like Obsidian framed a file as a note in a knowledge graph, which was overkill and unintuitive for someone who just had a document to read or edit.

Verbatim (P3, writer) — coded: System overhead: "I don't want to build a second brain, I just have this one file I need to read and tweak."

Dashboard — Markdown is read in the wrong kind of tool

Markdown is read in the wrong kind of tool
Scope: reading test (n=26) + survey (n=180)
Guiding question: How and where do people read long markdown?

  Read long markdown in a code / plain editor .. 58%
  Converted a .md to another format to read it .. 44%
  Read a long .md past its halfway point ........ 38%

Key Insight: The format the AI era produces is read in tools built for
syntax, so people abandon the document or leave the format to read it.

Define — A .md had to read like a real document, with the typographic control of a reader, without adopting a notes system

In this section: POV · How Might We · Principles · Insight→decision map

POV statement. A person with a long .md needs to read and edit it with the legibility of a real document reader, without adopting a notes system, because markdown is now a document they read at length and most tools render it as code, frame it as a note, or render it shallow.

How Might We

How might we give a .md the typographic control that makes long-form reading comfortable?
How might we let someone read, edit, and organize markdown files without the overhead of a knowledge-management system?
How might we keep the .md as the editable, exportable source while presenting it as a readable document?

Design principles (each traceable to an insight)

Legibility is the feature. The reader exposes typeface, size, heading scale, line height, text and heading weight, text opacity, and light or dark mode. (Insight 1)
The .md stays the source. Files are edited live and imported and exported as plain markdown, so the document the user moves around stays markdown. (Insight 2)
Utilitarian organization only. Simple folders and favorites, with no graph or second-brain model to adopt. (Insight 3)
Built for long documents. A generated table of contents, a reading-progress bar, an estimated reading time, and a saved reading position support reading at length. (Insight 1)

Insight → decision map

Insight (from Empathize)	Concrete design decision
Long markdown read in code editors, 38% completion	A reader with full typographic control (typeface, size, heading scale, line height, weights, opacity, light/dark) makes a .md read like a document
44% leave the format to read it	The reader and a source-visible editor work on the markdown itself, with fast import and export, so reading and editing never require conversion
Note apps impose an unwanted system	Files sit in simple folders with favorites, with a generated TOC, progress bar, reading time, and saved position, and none of a knowledge-graph model

Ideate & Craft — The .md stayed the source; a reader layer gave it typographic control, a TOC, and reading progress

In this section: Design execution · Before → after · Other deliverables

Design execution

The reader — opening a .md presents it as a clean document, with controls for typeface (sans or serif), font size, heading scale, line height, text weight, heading weight, and text opacity, plus light and dark mode, so a reader tunes legibility to the document and the screen.
Long-document support — a table of contents is generated from the heading hierarchy for navigation, a subtle progress bar and an estimated reading time track the read, and the reading position saves automatically or on demand for picking a long file back up.
The editor — files are created in an intuitive editor or by writing markdown directly with live preview, and the markdown source stays visible and editable, with fast import and export.
Organization — files sit in simple folders with favorites, ordered directly, as utilitarian documents.
Listen instead of read — a markdown file can be turned from text into audio (text-to-speech), for hands-free reading or accessibility, so a long document can be listened to rather than read.
Cross-device — the workspace works across devices, with reading settings and position carried along, so a document started on one screen continues on another.

Before → after

	Before (code editor / note app)	After (MD Render)
Reading a long .md	Monospace, raw, fatiguing	A document with typographic control
Reading comfortably	Convert to a doc or PDF	Read the markdown in place
Navigating a long file	Scroll and search	Generated TOC, progress, saved position
Organizing	A note in a knowledge graph	Simple folders and favorites

Other deliverables

Built in Figma with Dev Mode handoff: the reader and its typographic control system, the generated-TOC and reading-progress patterns, the source-visible editor with live preview, and the import, export, and text-to-speech flows.

Dashboard — Typographic control lifts long-read completion

Typographic control lifts long-read completion
Scope: Last 30 days · pilot (65 users)
Guiding question: Did readers get through long markdown documents?

  Read a long .md past its halfway point ... 38% (code editor) → 78% (reader)
  Converted a .md elsewhere to read it ..... 44% → 9%
  Adjusted at least one typographic setting  47%

Key Insight: Letting readers tune type to the document and the screen got
them through long files and ended the convert-to-read workaround.

Prototype / Test — A single optimal reading default tested well and left half the readers adjusting it; exposing the typographic controls lifted long-read completion

In this section: The experiment · What it taught

The first build shipped one carefully chosen reading layout (a fixed typeface, size, and spacing meant to be optimal) on the usual principle that a strong default beats a panel of knobs. It was A/B tested against the same default plus exposed typographic controls in Statsig across the pilot.

The failed variant. The fixed default read well in first impressions and got 61% of readers past the halfway point, well above the code-editor baseline, but legibility for long reading turned out to be personal and document-dependent: dense specs, small screens, and varied eyesight meant one layout did not fit everyone, and the readers it did not fit still dropped. With controls exposed, 47% of readers changed at least one setting and completion reached 78%.

One optimal default beats code, and controls beat one default
Scope: Statsig A/B · pilot · spring 2025 · ~32 users / arm
Guiding question: Which reading model gets people through long markdown?

  Baseline — Code / plain-text editor ........ 38%   (real-world reading test)

  Variant A — Fixed optimal reading default
    Long-read completion ............ 61%
    Readers who could not adjust .... dropped at the same points

  Variant B — Default + exposed typographic controls
    Long-read completion ............ 78%
    Readers who adjusted a setting .. 47%

Read with care: ~32 users per arm; the completion gaps are large and
consistent, the 30-day retention figure (in Outcomes) is directional.

Key Insight: A good default beat the code editor, and exposing the controls
beat the default, because long-form legibility is personal.

What it taught. For long-form reading, legibility is personal and document- and device-dependent, so the typographic controls are the feature, and a single fixed default leaves a large minority unable to read comfortably. The default-plus-controls model shipped.

Outcomes & reflections

In this section: Causal chain · Limitations · Competitive context · Reflections

Causal chain (pilot, 65 users)

The numbers below run two comparisons, kept separate. Against the real-world baseline, the code editor got readers past the halfway point 38% of the time; the shipped reader (default + controls) reached 78% — and the A/B showed each step earned its place (code editor 38% → fixed default 61% → default + controls 78%). The controls let each reader tune type to the document and the screen, so people stopped leaving the format to read it, with the convert-to-read workaround dropping from 44% → 9%; the generated TOC, progress bar, and saved reading position got readers back into long files, and the workspace became where they kept and read their markdown, lifting day-30 retention from 40% → 58% (the 40% baseline from the fixed-default cohort).

Metric	Baseline	Result	What it compares
Long-read completion (past halfway)	38% (code editor)	78% (reader)	real-world vs shipped tool
Converted a .md elsewhere to read it	44% (real-world)	9% (tool)	real-world vs shipped tool
Readers who tuned typography	—	47%	personal legibility used
Day-30 retention (directional)	40% (fixed-default cohort)	58% (default+controls cohort)	rejected variant vs shipped

Scale note: as markdown becomes the format people exchange with AI, the volume of long documents to read keeps growing, so a readable home for them sees rising use over time.

Limitations (stated, because a portfolio claim is only as strong as what it concedes)

Small pilot. 65 users, ~32 per A/B arm. The completion and convert-to-read effects are large and consistent; the 30-day retention lift is directional.
Short-horizon reading test. Completion was measured on a single long document per participant, not across the range of lengths and densities the problem spans.
A forming, fast-moving category. Lightweight markdown viewers aimed at AI output are appearing quickly; the wedge depends on staying deeper on reading control than they are, which is a moving target.
Cross-device depends on sync. Carrying reading settings and position across devices assumes a sync layer; offline or conflicting edits need handling the reader study did not cover.

Competitive context

The case's premise — that markdown became a reading format in the AI era — is now visibly true, and a niche of lightweight markdown viewers has formed around exactly it: Marked 2 and MacMD Viewer for reading .md, and newer tools like Meva and MDHero positioned explicitly for reading AI/Claude/ChatGPT output. So the gap is no longer "nowhere to read markdown." The defensible wedge is narrower and is the one the A/B proved: depth of typographic control as the feature (exposed controls beat even a strong fixed default, because long-form legibility is personal), plus the long-document reading apparatus (TOC, progress, reading time, saved position), reader and editor and light organization in one, and cross-device where most competitors are desktop-bound. Editor-first tools (iA Writer, Typora) read well but carry library and writing overhead; viewer-first tools read but are shallow on control. MD Render's claim is the reading-control depth between them.

Reflections (transferable principles)

For long-form reading, legibility is personal and depends on the document and the device, so typographic control is the feature; a single fixed default leaves a large minority unable to read comfortably. (The A/B is the evidence: a strong default beat code, and controls beat the default.)
A format people exchange with machines has to keep its source visible and editable, with readability added on top, so the document stays the artifact the user moves around.
Meeting a new everyday use of a format means giving it the conventions of the document tools it now competes with — a reader, a table of contents, a reading time — without importing the heavier system other tools wrap it in.