← ceesaxp.github.io
Why Features Status Architecture Download
#

Writ

// What You Write Is What You Mean

A fast, native macOS Markdown editor for technical writing. Plain text in, publication-quality technical preview out. GitHub-Flavored Markdown, code, math, Mermaid diagrams, and export-ready typography — all bundled, all local, all yours.

Swift 6 macOS 14+ AppKit · TextKit Local-First MVP v0.5.2
Download v0.5.2 (.dmg) View on GitHub Read the PRD

macOS 14+ on Apple Silicon. Notarized & stapled — opens without a Gatekeeper prompt.

🤔 Why Writ?

Most Markdown editors are either Electron blobs that idle at 400 MB of RAM, rich-text WYSIWYGs that secretly mangle your .md on save, or cloud-locked notebooks that hold your prose hostage behind a subscription.

Writ takes the opposite stance: plain text is the canonical format, your files live where you put them, and the preview renders structure and meaning — not a fake page of decorative font choices.

The principle is WYWIWYM — What You Write Is What You Mean. You write Markdown. Writ shows you what it means — including math, diagrams, and code — without ever pretending to be the document itself.

✨ Features

📝 Native Editor
AppKit / TextKit NSTextView, not SwiftUI TextEditor. Real undo, find/replace, tabs, autosave, spellcheck — all the macOS behaviors you'd expect.
🔀 Three Modes
Source-only, preview-only, or split. Persistent WKWebView preview with debounced, off-main-thread updates so typing never blocks.
📘 GitHub-Flavored Markdown
Powered by apple/swift-markdown backed by cmark-gfm. Tables, task lists, strikethrough, the lot.
∑ KaTeX Math
Inline $…$ and display $$…$$ math rendered with KaTeX. MathJax bundled as a runtime alternate.
🌊 Mermaid Diagrams
Fenced ```mermaid blocks render to native SVG diagrams — flowcharts, sequence, class, state, and more.
🌱 PlantUML Aware
PlantUML fenced blocks are recognized in the MVP, with a graceful "local rendering deferred" notice in place of a spinner.
💡 Syntax-Highlighted Code
highlight.js in preview, dark/light aware. Code stays code — no smart quotes, no autocorrect ambushes.
📤 Export
HTML and PDF export paths today, with live-rendered math & Mermaid in export landing soon. The output is what you saw.
⚡ Performance Budget
Open a 1 MB Markdown file editable in <1 s on Apple Silicon. 5 MB stays editable. No full attributed-string rebuild on every keystroke.
🌗 Dark / Light Preview
Preview CSS is system-aware. Switch your Mac to dark mode and the preview follows — no theme picker required.
🔌 Offline by Default
KaTeX, MathJax, Mermaid, and highlight.js are bundled. No CDN, no remote rendering, no network needed.
🚫 No Cloud, No Lock-In
No accounts, no sync service, no proprietary format. Your .md file is your .md file.

🚧 MVP Status

✓ Shipped

  • Document-based app for .md, .markdown, .txt
  • AppKit / TextKit editor surface
  • Native undo, find/replace, tabs, autosave
  • Source · Preview · Split modes
  • GFM rendering + code highlighting
  • KaTeX math, Mermaid diagrams
  • PlantUML block recognition
  • Status bar (words, line:col, render state)
  • HTML & PDF export
  • Swift package test suites

→ In Progress

  • Sandboxed local image / SVG preview
  • Preview HTML sanitization
  • Export with live-rendered math & Mermaid
  • Stronger scroll sync
  • Incremental editor highlighting for large files
  • Optional line numbers
  • Folder / project mode
  • Optional local PlantUML rendering

🏗️ Architecture

A native macOS app on top of a small set of local Swift packages. No IPC, no Electron, no remote services.

App/ hosts the AppKit document app, editor, preview, menu, export, and window controllers. WritCore handles document snapshots, revisions, hashes, render jobs, large-document mode, and technical-block models. WritParser does Markdown parsing, math preprocessing, technical-block extraction, and HTML emission. WritRender manages preview scheduling, technical-block caching, export helpers, and the bridge payloads.

The editor is NSTextView with TextKit 2 where practical. The preview is a persistent WKWebView loaded once per document, then updated through a small JavaScript bridge — window.Writ.update(...). Parsing and preview scheduling run off the main thread so typing stays responsive.

Render pipeline:

  1. User edits Markdown in the native text editor
  2. Debounce schedules a preview generation
  3. Markdown parsing runs off the main thread
  4. Technical blocks extracted (math, Mermaid, PlantUML, SVG/image, code)
  5. HTML emitted with stable block IDs for preview coordination
  6. The existing WKWebView receives an update payload via the bridge
  7. Bundled JS renders math, diagrams, and syntax highlighting
  8. Expensive renders cached by content hash; errors shown inline, never modal

⏱️ Performance Targets

< 1 s Warm launch to editable window (Apple Silicon)
< 1 s 1 MB Markdown file to editable state
5 MB Editable without blocking the main thread
< 500 ms Preview update for a 10 KB document after debounce
60 fps Native scroll for large files
0 Full attributed-string rebuilds per keystroke

🔒 Privacy & Offline

Writ is local-first: no account, no telemetry in the MVP, no remote rendering services by default. PlantUML remote servers are explicitly out of scope. KaTeX, MathJax, Mermaid, and highlight.js are bundled in the app for offline use — your prose, code, and diagrams never leave the machine.

📦 Install or Build

⬇️ Download the DMG

Notarized + stapled. macOS 14+ (Sonoma) or later. Open the DMG and drag Writ to Applications.

Writ-0.5.2.dmg · 7.0 MB

📥 Clone the Repo

Requires macOS 14+, Xcode with Swift 6, and (if regenerating the project) XcodeGen.

git clone https://github.com/Ceesaxp/Writ.app.git cd Writ.app open Writ.xcodeproj

🔨 Command Line Build

Build a Debug configuration straight from the CLI.

xcodebuild \ -project Writ.xcodeproj \ -scheme Writ \ -configuration Debug build

🧪 Run Tests

Each package has its own test suite.

swift test --package-path Packages/WritCore swift test --package-path Packages/WritParser swift test --package-path Packages/WritRender

📊 Benchmarks

Parser and fixture benchmark tooling lives in Benchmarks/.

swift run --package-path Benchmarks writ-fixtures swift run --package-path Benchmarks writ-bench

🚷 Deliberately Not This

Writ's MVP non-goals, stated up front so nobody has to ask:

WYSIWYG / Typora-style inline rich editing.   Cloud sync, collaboration, accounts, proprietary storage.   Plugin system.   AI writing or generation features.   Mobile, iPadOS, Windows, or Linux.   A full publishing platform.   A heavy custom theme engine.

If a feature is missing, that's the answer. If it's in TODO.md, it's on the way.