On this page

Wymark documentation

Wymark is a local-first markdown editor with review built in. It gives you two views of the same file on disk – a WYSIWYG view and a raw markdown view – plus an always-on review layer: whatever moved your document – a commit on someone else’s branch, a version you saved last week, a colleague’s rewrite, a draft you handed to a tool – comes back as changes you can read, accept, reject and comment on.

Three promises shape everything else:

  • Your file is the source of truth. Both editor views display the file on disk; every edit reaches the disk promptly and in order; nothing rewrites content you did not touch.
  • Review is always on. There is no mode to enter and no commit ceremony. The moment the file differs from your baseline, the difference is visible and actionable.
  • Everything lives in the file or next to it. Comments are plain HTML comment markers inside your markdown. Review history lives in a local database on your machine. Nothing is uploaded without your say-so – the one thing that ever leaves is a crash report you choose to send, and you can read it before it goes.

Where to start

New here? Try a review in the browser before you install anything, then get started.

Guide: how to do things

Concepts: the model

Reference: facts to look up

  • Keyboard shortcuts – every shortcut, grouped as the app groups them.
  • Markdown support – the format, and what the editor does and does not do to your file.
  • The editor – the two views, the toolbar, selecting and copying, paste, undo.
  • Text – headings, bold and italic, line breaks, escapes, math.
  • Lists, tables and blocks – lists, tables, quotes and alerts, code blocks, dividers.
  • Links, footnotes and pictures – links, heading links, footnotes, pictures.
  • Diagrams – mermaid diagrams drawn where you wrote them, styled from inside the file.
  • Drawings – sketch with Excalidraw; the drawing is a plain PNG that opens back up as editable strokes.
  • HTML – the HTML tags the Formatted view draws, the same ones github.com renders.
  • History bundles (.mdh) – sending a document together with its history. It is a zip of markdown files; nothing proprietary.
  • Privacy – everything that leaves your machine, and everything written beside your files.

How it works: the design, and the formats

For readers who want to know why Wymark behaves the way it does, or who are building a tool that reads its files.

Reading these docs

Wymark serves readers coming from very different places: Word and Google Docs, markdown writing without git, and git-native development. Concept pages carry short “coming from …” notes for each background – use the Reading as picker at the top of any page to show only the framing written for you, or keep all of them visible.

And one more thing: every page in these docs is itself a markdown file. Use the Source toggle at the top of any page to see the source – the same gesture as Wymark’s own Formatted/Source switch. Agents and scripts can fetch any page as markdown by appending index.md to its URL, and /llms.txt indexes them all.


# Wymark documentation

Wymark is a local-first markdown editor with review built in. It gives you two views of the same file on disk -- a WYSIWYG view and a raw markdown view -- plus an always-on review layer: whatever moved your document -- a commit on someone else's branch, a version you saved last week, a colleague's rewrite, a draft you handed to a tool -- comes back as changes you can read, accept, reject and comment on.

Three promises shape everything else:

- **Your file is the source of truth.** Both editor views display the file on disk; every edit reaches the disk promptly and in order; nothing rewrites content you did not touch.
- **Review is always on.** There is no mode to enter and no commit ceremony. The moment the file differs from your baseline, the difference is visible and actionable.
- **Everything lives in the file or next to it.** Comments are plain HTML comment markers inside your markdown. Review history lives in a local database on your machine. Nothing is uploaded without your say-so -- the one thing that ever leaves is a crash report you choose to send, and you can read it before it goes.

## Where to start

**New here?** [Try a review](/docs/concepts/try-a-review) in the browser before you install anything, then [get started](/docs/guide/getting-started).

### Guide: how to do things

- [Getting started](/docs/guide/getting-started) -- requirements, installing, the first launch, opening your files.
- [Files, tabs and windows](/docs/guide/workspace) -- folders, tabs, panes and windows.
- [Exporting to Word and PDF](/docs/guide/exporting) -- with real comments and tracked changes.
- [Changes from outside Wymark](/docs/guide/changes-from-outside) -- pasted text or a tool's edits, arriving as changes to review.
- [AI sidecar](/docs/guide/ai-sidecar) -- the toolbar switch that lets a tool editing your file see what you are reviewing.

### Concepts: the model

- [Review: baseline, accept and reject, versions](/docs/concepts/review) -- the core mental model.
- [Comparing against git and past versions](/docs/concepts/git) -- the `vs …` menu: commits, saved versions, and read-only overlays.
- [Comments](/docs/concepts/comments) -- comments that live in your file, not in a database.

### Reference: facts to look up

- [Keyboard shortcuts](/docs/reference/keyboard-shortcuts) -- every shortcut, grouped as the app groups them.
- [Markdown support](/docs/reference/markdown) -- the format, and what the editor does and does not do to your file.
- [The editor](/docs/reference/editor) -- the two views, the toolbar, selecting and copying, paste, undo.
- [Text](/docs/reference/text) -- headings, bold and italic, line breaks, escapes, math.
- [Lists, tables and blocks](/docs/reference/lists-tables-blocks) -- lists, tables, quotes and alerts, code blocks, dividers.
- [Links, footnotes and pictures](/docs/reference/links-footnotes-pictures) -- links, heading links, footnotes, pictures.
- [Diagrams](/docs/reference/diagrams) -- mermaid diagrams drawn where you wrote them, styled from inside the file.
- [Drawings](/docs/reference/drawings) -- sketch with Excalidraw; the drawing is a plain PNG that opens back up as editable strokes.
- [HTML](/docs/reference/html) -- the HTML tags the Formatted view draws, the same ones github.com renders.
- [History bundles (`.mdh`)](/docs/reference/history-bundles) -- sending a document together with its history. It is a zip of markdown files; nothing proprietary.
- [Privacy](/docs/reference/privacy) -- everything that leaves your machine, and everything written beside your files.

### How it works: the design, and the formats

For readers who want to know why Wymark behaves the way it does, or who are building a tool that reads its files.

- [Why the diff is always correct, but not always pretty](/docs/how-it-works/diff) -- the design trade-off behind the review engine.
- [Why comments live in the file](/docs/how-it-works/comments) -- the reasoning for markers in the markdown instead of a database.
- [Comment marker syntax](/docs/how-it-works/markers) -- the exact format, for power users and tool authors.
- [Why a history bundle is a zip of markdown files](/docs/how-it-works/history-bundles) -- the reasoning behind the `.mdh` format.
- [For AI agents](/docs/agents) -- how an AI reads the live diff from the review sidecar and behaves inside a Wymark-managed file.

## Reading these docs

Wymark serves readers coming from very different places: Word and Google Docs, markdown writing without git, and git-native development. Concept pages carry short "coming from ..." notes for each background -- use the **Reading as** picker at the top of any page to show only the framing written for you, or keep all of them visible.

And one more thing: every page in these docs is itself a markdown file. Use the **Source** toggle at the top of any page to see the source -- the same gesture as Wymark's own Formatted/Source switch. Agents and scripts can fetch any page as markdown by appending `index.md` to its URL, and [/llms.txt](/llms.txt) indexes them all.