https://github.com/cybermaak/maakdown
Fast, local-first desktop Markdown viewer for technical docs and notes — clean typography, code highlighting, KaTeX math, Mermaid diagrams, wikilinks, tabs. macOS (signed & notarized), Windows, Linux.
https://github.com/cybermaak/maakdown
cross-platform desktop-app golang katex knowledge-base local-first markdown markdown-reader markdown-viewer mermaid note-taking notes svelte wails wikilinks
Last synced: 5 days ago
JSON representation
Fast, local-first desktop Markdown viewer for technical docs and notes — clean typography, code highlighting, KaTeX math, Mermaid diagrams, wikilinks, tabs. macOS (signed & notarized), Windows, Linux.
- Host: GitHub
- URL: https://github.com/cybermaak/maakdown
- Owner: cybermaak
- License: mit
- Created: 2026-06-07T04:38:55.000Z (17 days ago)
- Default Branch: main
- Last Pushed: 2026-06-11T08:18:22.000Z (12 days ago)
- Last Synced: 2026-06-11T10:09:31.375Z (12 days ago)
- Topics: cross-platform, desktop-app, golang, katex, knowledge-base, local-first, markdown, markdown-reader, markdown-viewer, mermaid, note-taking, notes, svelte, wails, wikilinks
- Language: TypeScript
- Homepage: https://cybermaak.dev/maakdown/
- Size: 8.79 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Maakdown
**A beautiful, distraction-free desktop app for reading your Markdown.**
[](https://github.com/cybermaak/maakdown/actions)
[](LICENSE)
[](#download)
Maakdown is a fast, local-first Markdown viewer designed for technical documents, personal notes, and knowledge bases. Open any Markdown file and see it the way you meant it — clean typography, rich code formatting, math, and diagrams, all in a calm workspace.
---
## 🌟 Why Maakdown?
We built Maakdown because reading Markdown shouldn't feel like staring at a raw code editor, nor should it require a heavyweight, slow electron app.
- **A Genuinely Nice Reading Experience**: Warm, book-like themes, careful typography, and a focus mode that clears everything but the words. Tune the font, size, line height, and width to taste.
- **Lightning Fast on Massive Files**: Open a 10,000-line document and it still scrolls smoothly and stays light on memory. Text appears instantly, and richer details fill in as you read.
- **Built for Technical Minds**: Syntax-highlighted code, KaTeX math, Mermaid diagrams, tables, task lists, callouts, footnotes, and local images all just work.
- **Local-First & Private**: Your files never leave your machine. Work offline across many notes using tabs, recent files, and a session that restores itself perfectly the next time you open the app.
- **Keyboard & Navigation Ready**: Search the current document, navigate with a command palette, jump between notes via wikilinks, and print or export to PDF whenever you need a copy.
---
## ✨ Features at a Glance
| Feature | Details |
|---|---|
| **Standard Markdown** | Full support for CommonMark + GFM tables, task lists, strikethrough, autolinks, and footnotes. |
| **Code & Syntax** | Fenced-code highlighting via highlight.js (default), with optional Shiki integration. |
| **Math & Diagrams** | Inline and block math rendered with KaTeX. Mermaid diagrams lazy-load on viewport entry. |
| **Metadata & Callouts** | YAML frontmatter surfaces as a clean document masthead. Full support for GitHub/Obsidian-style callouts. |
| **Seamless Navigation** | Hover-revealed outline with scroll-spy, internal `#anchors`, and per-tab history. |
| **Wikilinks** | Native `[[Note Name]]` support resolved through a blazing-fast Go-built vault index. |
| **Workspace & Output** | Tabbed documents, drag-and-drop, native print, and system print-to-PDF support. |
| **Custom Appearance** | Light/dark themes, focus mode, and highly configurable typography settings. |
---
## 📸 Screenshots
Dark theme with rendered Mermaid diagrams
Syntax-highlighted code and KaTeX math
Command palette for fast keyboard navigation
Note: Every screenshot above is generated from the real app rendering sample documents. You can regenerate them at any time in development.
---
## 🚀 Download & Installation
Grab the latest build for your OS from the [GitHub Releases](https://github.com/cybermaak/maakdown/releases) page — or visit the [project homepage](https://cybermaak.github.io/maakdown/):
| Platform | Artifact | Notes |
|---|---|---|
| **macOS** (Apple silicon) | `.dmg` or `.zip` | **Signed & notarized** — opens without Gatekeeper warnings |
| **Windows** (x64) | `.zip` | ⚠️ **Work in progress** — the current build is glitchy; a fix is underway. Unsigned (SmartScreen may warn) |
| **Linux** (x64) | `.tar.gz` | Requires WebKit2GTK (preinstalled on most desktop distros) |
Extract (or drag the dmg's app to Applications) and launch.
---
## 🛠️ For Developers & Contributors
Maakdown is an open-source project built with performance and simplicity in mind. We use a **Go backend** via [Wails v2](https://wails.io/) paired with a **Svelte 5 + TypeScript** frontend.
### Architecture Highlights
- **Go Backend**: Handles file operations, safe-save watcher debounce, tokenized loopback asset server, and blazing-fast wikilink indexing.
- **Svelte 5 Frontend**: A framework-agnostic core running a unified/remark/rehype pipeline, with a fully virtualized reader UI.
### Getting Started
Prerequisites: **Go 1.22+**, **Node.js 20.19+**, and the **Wails CLI v2.11.x**.
```bash
# Clone the repository
git clone https://github.com/cybermaak/maakdown.git
cd maakdown
# Install frontend dependencies
cd frontend && npm install && cd ..
# Start the dev server (hot-reloads frontend in a native WebView)
wails dev
```
For comprehensive documentation on the codebase, project rules, and contributing guidelines, please refer to:
- [`docs/markdown-viewer-design-spec.md`](docs/markdown-viewer-design-spec.md) — Product & Technical Spec
- [`AGENTS.md`](AGENTS.md) — Repo Operating Rules
- [`DEV_CONTEXT.md`](DEV_CONTEXT.md) — Current Project State & Completed Tasks
---
## 📜 License
Maakdown is open-source software licensed under the [MIT License](LICENSE).