Remarkdown

A desktop reader for markdown documents with PDF-style annotations — highlight, leave a re.mark, and doodle on top of your docs. Annotations save as a human-readable JSON sidecar next to the source file.

Reading view — vertical watermark, syntax-highlighted article, right-gutter minimap, animated BETA pin under the wordmark.	Navigation, checkboxes & code — drag in the right-gutter minimap to jump anywhere in long documents; task-list - [ ] items render as live checkboxes; fenced code blocks pick up real per-language Shiki theming (Rust shown here).
Annotate freely — highlight passages in 5 preset colors, drop re.marks anchored to a single word with inline popovers, and doodle on top of the text with the freehand draw tool.	Settings panel — 18 preferences across appearance, reading, annotation, and updates.

🎉 0.5.4 Beta — latest

0.5.4-beta adds a right-margin marginalia column that shows every re.mark as an editable liquid-glass card aligned with its anchor — click to edit in place, with a stream of luminous orbs that flows from the in-doc dot into the card. Cards push each other down to avoid collisions, and a configurable bullet-cap keeps re.marks anchored in list items from spilling context across other items. Also: Open new documents in Focus mode, Minimap popout in Focus mode with a hover-reveal peek zone, an entirely redesigned title-bar with colour-coded blooming hover orbs, and a reorganized Settings panel with 6 balanced sections.

Earlier in the 0.5 line: per-doc reading progress + ToC popover + aggregated changelog + hamburger overlay (0.5.3); mermaid + Obsidian-style callouts + orphan re-attach + file watcher (0.5.2); drawings anchored to text, reader mode, drawing roughness slider (0.5.1).

⚠️ If you're running a pre-beta build (0.4.x or earlier): auto-update wasn't shipped yet, so your installed copy can't pull these betas on its own. Download the latest installer from the Releases page and run it once — every release after this one will arrive automatically via the in-app updater.

⬇️ Download

Pre-built Windows installers are published with each tagged release. Grab the latest from the Releases page:

• remarkdown_<version>_x64-setup.exe — NSIS installer (recommended)
• MSI installers return for stable releases — beta builds are NSIS-only because Windows MSI's version field doesn't accept alphanumeric pre-release tags like -beta.

Already installed? Open Hamburger menu → Check for updates… to grab the next release without leaving the app.

✨ Why remarkdown?

When you're reading a technical spec, a paper, or a book chapter in markdown, you often want to highlight key passages, scribble in the margins, and leave re.marks — the same mental model you'd use with a paper book or a PDF. Most markdown viewers are read-only, and most annotation tools require converting to PDF first.

remarkdown reads plain markdown from disk, renders it in a clean dark UI, and lets you annotate on top. Your annotations save alongside the source file as a plain-text JSON sidecar — so they stay with your notes, survive document edits where possible, and can be read back by any tool (including LLMs) without the original document loaded.

🎨 Features

Annotation

• 🖍 Highlights in 5 preset colors, rendered via the CSS Custom Highlight API — no DOM mutation, handles overlaps cleanly
• 📝 re.marks (sticky-note style) anchored to the right margin of the chosen word, with click-off-to-close popovers and punctuation-aware word boundary detection
• 📋 re.marks side panel — bottom-left pill (next to the Table of Contents button) opens a glass-styled list of every re.mark with N sentences of surrounding context (configurable 1-5 sentences, optional paragraph-stop, optional cap-to-bullet). Click an entry to jump. The wordmark's dot orbits around it on hover.
• 📜 Marginalia column [prototype] — right-margin liquid-glass cards, one per re.mark, vertically aligned with the anchor and showing the same sentence context. Click any card to edit in place; a stream of glowing dots flows from the in-doc pin into the card while editing. Push-down collision avoidance keeps cards readable even when re.marks cluster.
• ✏️ Drawings anchored to text — freehand SVG strokes that follow text reflow + zoom; opt-in auto-transform turns closed loops around words into ellipses, lines under text into underlines, vertical margin lines into margin bars, etc.; drawing roughness slider in Settings (0 = crisp, 3 = very sketchy)
• 🧹 Eraser tool — single-click delete for any highlight, re.mark, or drawing without confirmation
• 🔎 Robust anchoring — W3C-style text-quote selectors with fast path (matching block) and slow path (cross-block similarity scoring); annotations re-resolve after edits where possible
• 👻 Orphan panel + re-attach — when an edit moves a phrase beyond recognition, the annotation goes to an "orphaned" list. Each orphan has a Re-attach button — click it, then select the new location in the article and the annotation snaps to it

Reading

• 📂 Drag-drop any .md file from Explorer onto the window to open it
• 🕘 Open Recent menu with missing-file detection, grey-out, and per-document reading progress %
• 📑 Reading progress — scroll position is remembered per file; reopen a doc and you land where you left off
• 🗂 Table-of-contents popover — pill above the Focus toggle lists every h1–h4; click an entry to jump
• 🗺 VS Code-style minimap in the right gutter for long-document navigation; mirrors the live article DOM so mermaid + callouts show up at the right scale
• 🧩 Mermaid diagrams — fenced ```mermaid blocks render as SVG; lazy-loaded so the bundle stays small
• 💬 Obsidian-style callouts — blockquotes prefixed with [!type] render as themed boxes (note, info, tip, warning, danger, bug, quote, abstract, etc.); foldable variants [!type]+ / [!type]-
• 👁 File watcher — edit the open file in another editor and remarkdown reloads within ~1s; surviving annotations stay anchored, others go to the Orphan panel
• 📖 Focus mode — toggle a clean reading view that hides every chrome layer; title-bar drag + resize grip stay invisibly clickable. Optionally open new documents straight into Focus mode + peek the minimap on hover when active
• 🔍 Zoom with Ctrl + / Ctrl - / Ctrl 0 — scales the entire article (and minimap) via a single CSS variable
• 🌓 Dark or light liquid-glass UI with a frameless custom title bar, hamburger menu, and bottom tool rail — designed to disappear while you read
• 🪞 Vertical filename watermark in the left margin (extreme size, low opacity, fades toward the article column)

First-run experience

• 👋 Welcome document opens automatically the first time you launch (toggleable hint in the corner to skip future launches)
• 📍 Hand-drawn tutorial overlay — six arrows + a bracket point at every piece of chrome the first time you see the welcome doc; dismiss for the session or hide forever
• 🎬 Animated splash with a re.md → remarkdown morph and an animated BETA pin

Window chrome

• 🖱 Hamburger hover morph — the wordmark animates from re.md → remarkdown whenever you hover the menu button (same choreography as the splash)
• 🎨 Title-bar window controls with colour-coded blooming hover orbs — amber for minimize, cyan for maximize, red for close — plus per-icon micro-animations (slide-down / scale / rotate)
• 🔧 Bottom-right resize grip — drag to resize, double-click to reset to the default 1100×780; double-click the title bar to toggle maximize
• 🏷 Animated BETA pin under the wordmark and on the splash, with glow-pulse + gradient drift + diagonal shine; auto-hides at 1.0+ stable

Auto-update

• ⬆️ In-app updater with manual "Check for updates…" in the hamburger menu and an optional auto-check on launch (Settings → off by default for paranoid users)
• 🔐 Ed25519-signed installers — every update verifies its signature against the public key baked into the app before installing; tampered installers are refused
• 📦 GitHub Releases as the distribution channel — manifest at /releases/latest/download/latest.json is what your installed copy polls

Settings

• ⚙️ Settings panel (hamburger → Settings…) persists 18 user preferences to settings.json in the OS app-data dir
• Appearance — dark/light theme, splash on/off, watermark on/off, watermark opacity
• Reading — default zoom, article column width, max recent files (slider + typeable badge), reopen-last-file on launch, hide annotation chrome, show welcome on launch, show tutorial overlay
• Annotation — default highlight color, default ink color, drawing idle-finalize duration, re.marks sentence-context count + paragraph-stop
• Save behaviour — sidecar write debounce
• Updates — auto-check on launch on/off
• All settings apply live; "Reset to defaults" restores everything in one click

Storage & resilience

• 💾 Atomic sidecar writes with configurable debounced saves; retry with exponential backoff on write failures; synchronous flush on window close
• 🛡 Error matrix — UTF-8 toast, corrupt-sidecar backup modal, write-retry banner, 2 MB size warning
• 🧪 Battle-tested — 390+ Vitest unit/component tests, Rust tests, Playwright E2E scenarios, zero svelte-check warnings

🎛 Tools

Color strip appears above the rail when Highlight or Draw is active (5 presets each).

⌨️ Keyboard shortcuts

💡 How the sidecar works

For every markdown file foo.md, remarkdown writes annotations to a sibling file foo.md.remarkdown.json:

{
  "_comment": "remarkdown annotations for: foo.md",
  "$schema": "remarkdown/v1",
  "document": {
    "path": "foo.md",
    "sha256": "7ac1bc…",
    "lastSeenBytes": 4821
  },
  "annotations": [
    {
      "id": "01HP8XYZ…",
      "type": "highlight",
      "color": "#ffd25a",
      "anchor": {
        "text": "must read slowly, and with care",
        "prefix": "The reader who would truly understand ",
        "suffix": ", turning the pages back when needed.",
        "blockHint": "p:3"
      },
      "createdAt": "2026-04-21T14:32:00Z",
      "updatedAt": "2026-04-21T14:32:00Z"
    }
  ]
}

The file is git-friendly, human-editable, and semantically rich enough for an LLM to understand every annotation without the source document loaded.

🚀 Getting started

Prerequisites

• Node.js 20+
• Rust (stable toolchain)
• Tauri 2 platform prerequisites: https://v2.tauri.app/start/prerequisites/

Run in development

git clone https://github.com/kaislate/remarkdown.git
cd remarkdown
npm install
npm run tauri dev

⏱ First cold build compiles the Rust toolchain + Tauri dependencies — expect 3–8 minutes. Subsequent launches are ~5 seconds.

Build a release installer

npm run tauri build

Produces a signed NSIS installer in src-tauri/target/release/bundle/nsis/. Cutting a release with the in-app updater enabled requires the Ed25519 signing key — see RELEASING.md for the full process.

🗺 Roadmap

✅ Shipped through 0.5.4-beta

• Reader MVP — Shiki syntax highlighting + KaTeX math + footnotes + task lists + tables + relative images
• All four annotation types (highlight, re.mark, drawing, eraser) with save/load round-trip
• Drawings anchored to text with optional auto-shape recognition + roughness slider
• re.marks side panel with configurable sentence-context, animated wordmark, ToC-adjacent placement
• Marginalia column [prototype] — right-margin liquid-glass cards with click-to-edit + flowing-dot connector + push-down collision avoidance
• Mermaid diagrams + Obsidian-style callouts with foldable variants
• Anchoring with orphan detection + re-attach UI
• File watcher — external edits reload within ~1s; survivors stay anchored
• Per-document reading progress + Table-of-contents popover for navigation
• In-app auto-update with manual + auto-check, Ed25519-signed installers, aggregated multi-version changelog
• Focus mode — hides every chrome layer; optional auto-enter on doc open; optional minimap-popout-on-hover
• Minimap, zoom, frameless window, splash
• Hamburger backdrop + X-cursor, blooming title-bar control orbs, hand-drawn welcome tutorial, animated BETA pin, hover wordmark morph
• 23-setting Settings panel (six sections, hairline separators) with persistent preferences and live apply
• Dark and light themes; full error matrix (UTF-8 toast, corrupt-sidecar backup, write-retry, 2 MB warning)
• 390+ Vitest tests, Rust tests, Playwright E2E coverage of the spec scenarios, 0 svelte-check warnings

🔮 Post-beta (deferred)

• Marginalia polish — measured (not estimated) card heights for tighter push-down, wide-doc / narrow-window adaptive layout, optional connector treatments
• Edit mode — slash-command for headings/lists, drag-and-drop mermaid diagrams + inline images. "a markdown editor for people who don't know what markdown is"
• Pre-release channel — wire up the auto-updater so opt-in users actually receive pre-release builds (currently only changelog filtering is implemented)
• Undo/redo action log
• Per-doc asset protocol scope tightening (security hardening)
• Wiki-links — [[link]] syntax across vault-style folders
• PDF/HTML export with baked-in annotations
• Cross-document commands — "summarize highlights across these N files"
• Collaboration — real-time sync / multi-user annotations

🧪 Testing

npm test              # 390+ Vitest unit + component tests
npm run check         # svelte-check (0 errors, 0 warnings)
npm run test:e2e      # Playwright end-to-end scenarios
cd src-tauri && cargo test   # Rust tests

🛠 Tech stack

📁 Project layout

remarkdown/
├── src/                     # Svelte 5 frontend
│   ├── lib/                 # Pure TS modules (anchoring, renderer, save, schema, …)
│   ├── components/          # Svelte components (Viewer, ToolRail, layers, modals, …)
│   ├── stores/              # Reactive state (doc, annots, tool, toasts, modals, …)
│   └── styles/              # Theme tokens (dark + light) + glass mixins + CSS highlight rules
├── src-tauri/               # Rust host
│   ├── capabilities/        # Tauri capability allowlists
│   └── src/                 # Invoke commands, atomic sidecar writes, recent-files persistence
├── scripts/                 # Build helpers (latest.json manifest generator)
├── tests/
│   ├── unit/                # Vitest unit tests
│   ├── component/           # @testing-library/svelte component tests
│   └── e2e/                 # Playwright end-to-end + support/
├── RELEASING.md             # End-to-end release/sign/publish process
└── README.md                # This file

🤝 Contributing

remarkdown is a personal project right now. If you find a bug or want a feature, please open an issue before opening a PR so we can talk about scope.

📜 License

TBD. Will settle on a license before a stable v1.0 tag ships.