Help & documentation

Everything you need to get productive with Simple MD in about ten minutes. If you're stuck on something not covered here, the troubleshooting section has the most common gotchas.

Simple MD is open source · github.com/robrighter/simple-md

Install & first run

Grab a build from the downloads page for your platform:

• macOS — universal .dmg for Apple Silicon and Intel. Drag Simple MD.app into Applications.
• Windows ARM64 — for Surface Pro X, Copilot+ PCs, and other ARM-based machines. Native, no emulation.
• Windows x86_64 — for 64-bit Intel and AMD processors. MSI installer, signed.

On first launch you'll see a welcome document. Simple MD doesn't ask for an account, an email, or a license key. Just open a folder or a file and start writing.

A quick tour

The window is two columns:

• Left rail — workspace tree and a unified Recents list. Right-click any file or folder for rename / delete.
• Main column — a thin top bar with file actions and mode tabs, then the tab strip, then the document, then the status bar.

The status bar at the bottom shows the last action, dirty indicator, current mode, word/line/character counts, and the file path. If the document came from an HTTPS URL, the path is a clickable link that opens the source.

Workspaces & files

A workspace is just a folder Simple MD knows about. You can have several open at once.

• Open a folder — click Open in the top bar, or drop a folder onto the window.
• Create a note — click New ▾ → Note. Simple MD appends .md if you forgot.
• Create a folder — New ▾ → Folder.
• Rename / delete — right-click any tree entry. Workspace roots can only be removed (the underlying folder is left untouched).
• Standalone files — open a single .md without adding its parent folder.
• Scratchpads — click the + on the tab strip for a temporary unsaved buffer. Saving prompts for a filename.

Recognized extensions

Simple MD treats .md, .markdown, .mdown, and .mkd as Markdown. Other extensions are ignored in the workspace tree even if they happen to contain Markdown.

The four modes

The mode tabs are in the top bar. Each open document remembers its mode independently, so you can have a draft in Text and a finished doc in Display at the same time.

Display

Read-only render. GitHub-flavored Markdown, syntax-highlighted code, KaTeX math, and inline charts. Use this when you're proofing, presenting, or just want a calm reading view.

Text

Pure Markdown source in CodeMirror 6. Syntax highlighting, list continuation, bracket matching, and a monospaced editing surface. Power-users live here.

Hybrid

True WYSIWYG. Type into the rendered view and Markdown is generated underneath, losslessly. Powered by Milkdown and ProseMirror. Best for prose-heavy writing.

Heads-up: Hybrid mode keys on the active document. Switching documents remounts the editor with fresh state, so your cursor jumps to the start. Switching modes on the same document is fine.

Split

Source on the left, rendered preview on the right. The two panes scroll together. Useful when you're tuning a tricky table or a chart spec.

Math with KaTeX

Inline math goes between dollar signs:

The mass-energy relation is $E = mc^2$.

Block math uses double dollars:

$$
\int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}
$$

KaTeX is bundled — Simple MD does not download fonts at runtime. Bad LaTeX renders red inline rather than breaking the document.

Inline charts

A fenced chart block is a JSON spec that renders as a real chart in Display, Hybrid, and the preview half of Split:

```chart
{
  "type": "bar",
  "title": "Q2 revenue by region",
  "data": [
    { "region": "NA", "revenue": 482 },
    { "region": "EU", "revenue": 311 },
    { "region": "APAC", "revenue": 207 }
  ]
}
```

Supported types: bar, line, area, and pie. Simple MD infers the x-axis key and series when you omit them, so most blocks are just { "type": "bar", "data": [...] }. A bad spec renders an inline error panel — never throws.

HTTPS import

Click Import… in the top bar and paste any HTTPS URL ending in a Markdown file. GitHub blob URLs are auto-rewritten to raw.githubusercontent.com.

Imported documents open as read-only buffers identified by their URL. Save them with Save to land them in your workspace.

Safety guard rails:

• HTTPS only — plain HTTP is rejected.
• 10 MB cap on the response.
• 30-second timeout, max 5 redirects.
• Content-type or extension or heuristic must look like Markdown.

Local AI assistant

The AI assistant is opt-in and entirely local. Click the AI callout in the top bar to open the right-edge panel. The first time, you'll be asked to:

1. Accept Google's Gemma terms of use (one-time, stored locally).
2. Choose a model variant.
3. Download it (one click, with a progress bar).

Variants

• Gemma 4 E2B (Q8_0) — about 5 GB. Higher quality, more memory.
• Gemma 4 E4B (Q4_K_M) — about 2.5 GB. Lighter, faster, still very capable.

Using it

The active document is auto-injected as context on every turn. After each assistant reply you have three actions:

• Insert — drops the reply at the cursor.
• Append — adds the reply at the end of the document.
• Replace — replaces the current selection (if any), and shows a side-by-side diff first because it's destructive.

Insert / Replace fall back to Append when the editor isn't mounted (i.e. you're in Display mode) — Simple MD shows a status pill explaining why.

Keyboard shortcuts

Modifier is ⌘ on macOS and Ctrl on Windows.

Default app for .md files

Simple MD registers itself as a handler for .md, .markdown, .mdown, and .mkd. To make it your default:

macOS

1. Right-click a .md file in Finder, choose Get Info.
2. Under Open with, pick Simple MD.
3. Click Change All… to apply to every .md file.

Windows

1. Right-click a .md file in Explorer, choose Open with → Choose another app.
2. Pick Simple MD and check Always use this app.

Once associated, double-clicking a Markdown file opens it in Simple MD even if the app isn't running. Drag-and-drop onto the dock / taskbar icon also works.

Privacy & data

• No telemetry. Simple MD does not phone home. There's no analytics SDK, no crash uploader, no opt-out toggle for "anonymous usage."
• No accounts. No sign-in, no license key, no email capture.
• No cloud sync. Your files live on your disk. Use any sync tool you like (iCloud, Dropbox, Syncthing) — Simple MD doesn't care.
• Sandboxed network. The only outbound calls are HTTPS imports you initiate and the optional one-time AI model download.

App-state metadata (recents, last-opened workspaces, AI license acceptance, AI model selection) lives in your OS's per-app data directory and never leaves the machine.

Troubleshooting

The app says my Markdown file is "missing"

Simple MD watches the filesystem and surfaces external changes via a banner above the document. If a file is moved or deleted by another tool, the tab will show a missing indicator. Reopen from the sidebar tree or use Recents.

An HTTPS import won't open

Common causes:

• The URL is HTTP, not HTTPS — Simple MD only fetches over TLS.
• The response is larger than 10 MB.
• The server returned a non-Markdown content type and the URL doesn't end in a Markdown extension.
• The host blocks non-browser User-Agents — try saving the file locally and opening it instead.

The AI panel is stuck on "Starting…"

Simple MD spawns llama-server and polls /health for up to 60 seconds. If the process dies before that, you'll see the tail of its stderr. Most often this is:

• Not enough RAM — try the smaller E4B variant.
• Model file corrupted mid-download — open the Models dialog and re-download. (Resumable downloads are on the roadmap; for now, retry restarts from scratch.)
• Antivirus quarantined the sidecar — whitelist the Simple MD app folder.

The Hybrid editor lost my cursor when I switched documents

Expected — the Hybrid editor remounts per document, so cursor position resets to the start. Switching modes on the same document keeps the cursor.

A chart block won't render

A bad chart JSON spec renders an inline red chart-error panel with the parser's complaint. Common issues are trailing commas, missing data arrays, or a type outside bar | line | area | pie.

Where are my settings stored?

• macOS: ~/Library/Application Support/Simple MD/
• Windows: %APPDATA%\Simple MD\

The folder contains ai-settings.json, downloaded model files (models/*.gguf), and any other per-app metadata. Deleting the folder is a clean reset.

Still stuck? File an issue at github.com/robrighter/simple-md/issues with your OS, app version, and a short reproduction. Logs from ~/Library/Logs/Simple MD/ (macOS) or %LOCALAPPDATA%\Simple MD\logs\ (Windows) help a lot.