Brewing Markdown, one document at a time.
A lightweight, local-first Markdown & Mermaid viewer built on Tauri v2 + Angular 21. HopsMD is a side project of the CloudBrew family — a small love letter to documentation and to a properly poured pint of beer.
- Pick a local folder (the Sudhaus / Brewhouse) via the native Tauri file dialog.
- Browse the recursive Markdown tree (the Rezeptbuch / Recipe Book) in a left sidebar.
- View any
.mdfile with full rendering: GitHub-flavoured Markdown, syntax-highlighted code (highlight.js, lazy-loaded), locally-resolved images, and live MermaidJS diagrams — plus math (KaTeX inline & display), footnotes, admonitions / callouts (NOTE / TIP / IMPORTANT / WARNING / CAUTION), task lists, emoji shortcodes, definition lists, and wiki-links ([[Page]]/[[Page|label]]). - Edit any
.mdfile — press Ctrl+E, double-click the article, or click the ✎ button to open a CodeMirror 6 source editor with Markdown syntax highlighting. Save with Ctrl+S (or the Save button); the file is written atomically and the view switches back to the rendered article instantly. - Tree file operations — right-click a node to create a new file or folder, rename (inline input), or delete (with confirmation). The tree refreshes automatically.
- More than Markdown — the tree also lists and opens plain-text files
(
.txt/.text/.log, shown verbatim and editable like Markdown), JSON (.json— collapsible tree view, editable with syntax highlighting), HTTP request files (.http/.rest— VS Code REST-Client format shown as request cards with method badge, headers, and body; editable, display only), PDFs (.pdf— embedded read-only viewer), emails (.eml/.msg— read-only header card + sanitised HTML or text body + attachment names), and common images (.png/.jpg/.gif/.svg/.webp/.bmp/.avif/.ico, fit-to-view with dimensions). HTML mail bodies are sanitised and the app's CSP blocks all remote content, so nothing phones home. - Theming & settings — a Settings page (
#/settings) with three colour presets (Brewpub Dark / Pilsner Light / High Contrast) plus per-token fine-tuning, body/mono fonts, text size, and DE/EN language — all persisted. A one-click theme switcher (☀️ / 🌙 / ◐) and the language toggle live in the top bar. - Auto-refresh on external edits — save in your editor, the view updates within ~250 ms.
- Live folder watching —
.mdfiles and folders added, removed, or renamed on disk appear in the tree automatically, no manual Nachschlag needed. - "Aktualisiert vor X" badge keeps you honest about how stale the open file is.
- Mermaid syntax errors surface as a
<pre>inside the affected diagram container — one bad batch never ruins the whole brew.
winget install CloudBrew.HopsMDThis is the friction-free path: winget install does not trigger the
Windows SmartScreen warning, even though the underlying installer is
unsigned. Once the manifest is merged into microsoft/winget-pkgs,
this is the install path we point everyone at.
The very first version is pending its manual submission to
microsoft/winget-pkgs— until that PR is merged (typically a day or two), use the manual download below.
For users who do not (yet) have winget, or who prefer downloading the installer directly: grab it from the latest GitHub Release.
HopsMD_<version>_x64-setup.exe— NSIS, smaller, per-machineHopsMD_<version>_x64_en-US.msi— MSI, group-policy friendly
First-time SmartScreen warning: the installer is unsigned. Windows will show "Windows protected your PC" — click More info → Run anyway to proceed. Code signing is parked until the project has accumulated enough public traction to qualify for one of the OSS code-signing programmes (e.g. SignPath OSS). Until then, the cleanest way to dodge the warning entirely is
winget install.
- Installed via winget?
winget upgrade CloudBrew.HopsMD - Installed manually? The in-app updater (when active) shows a banner "🍻 Neuer Sud — jetzt installieren" in the toolbar.
| Layer | Choice |
|---|---|
| Shell | Tauri v2 (Rust) — minimal: filesystem bridge only |
| UI | Angular 21 — standalone components, signals everywhere |
| Markdown | marked with a custom renderer |
| Editor | CodeMirror 6 — lazy-loaded source editor for text/Markdown |
| Diagrams | mermaid v11, lazy-loaded |
mail-parser (.eml) + msg_parser (.msg) |
|
| Sanitizer | DOMPurify (output then re-trusted for Angular's [innerHTML]) |
| Watcher | notify-debouncer-full — one recursive watch per workspace, 250 ms debounce |
| Installer | NSIS + MSI (WiX 3) via cargo tauri build |
| Updater | tauri-plugin-updater + ed25519 signatures (feature-gated) |
HopsMD/
├── src/ # Angular workspace (the Schankraum / tap room)
│ └── app/
│ ├── services/ # MarkdownStructure, MarkdownParser, MermaidRender, ColorTheme, Updater
│ ├── components/ # FileTree, MarkdownView, MarkdownEditor, EmailView, ImageView, SettingsPage, BreweryToolbar
│ ├── core/ # tauri-bridge, file-kind, path-utils, markdown-extensions
│ └── models/
├── src-tauri/ # Tauri / Rust shell (the Braukessel / brew kettle)
│ ├── src/commands/ # recipe_book.rs (tree + read/write), email.rs (.eml/.msg), watcher.rs
│ ├── capabilities/
│ └── tauri.conf.json
├── winget/ # winget-pkgs manifest templates
├── .github/workflows/ # release.yml + winget.yml
└── docs/RELEASE.md # human runbook
Prerequisites: Node 20+, Rust 1.78+, the platform Tauri toolchain (see https://v2.tauri.app/start/prerequisites/).
npm install
npm run tauri:dev # spins up Angular dev server on :3300 + Tauri shellStandalone Angular dev (no shell, for fast UI iteration):
npm start # serves on http://localhost:3300Production build:
npm run tauri:build
# → src-tauri/target/release/bundle/nsis/HopsMD_<v>_x64-setup.exe
# → src-tauri/target/release/bundle/msi/HopsMD_<v>_x64_en-US.msiA few user-facing labels lean into the theme — the code stays plain English so it is still searchable.
| UI term | Code term | Meaning |
|---|---|---|
| Sudhaus / Brewhouse | workspace root | The folder you opened |
| Rezeptbuch | recipe tree | The tree of .md files |
| Anstich | open / select | Opening a file |
| Maischen | loading | Async I/O in flight |
| Trübung | error | Syntax error in a Mermaid block |
| Frisch gezapft | freshly rendered | Successful Mermaid render |
| Nachschlag | refresh | Re-scan the workspace |
| Neuer Sud | new version | Available update |
Bug reports, fixes, and ideas welcome. See CONTRIBUTING.md
for the build/test/PR workflow and docs/RELEASE.md for
the release runbook. Security findings go through
GitHub Security Advisories
(see SECURITY.md).
Changes are tracked in CHANGELOG.md following
Keep a Changelog.
MIT © 2026 Ludwig Biermann.