HopsMD CloudBrew

documentation markdown mermaid tauri viewer

Use this command to install HopsMD:

winget install --id=CloudBrew.HopsMD -e

HopsMD is a lightweight, offline-first reader for Markdown documentation with live MermaidJS diagram rendering. It is a side project of the CloudBrew family — brewed with Tauri v2 + Angular 21 — and themed throughout with a love letter to a properly poured pint of beer.

HopsMD

> 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.

What it does (Phase 1 — Read Only)

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 .md file with full rendering: GitHub-flavoured Markdown, syntax-highlighted code, locally-resolved images, and live MermaidJS diagrams.
Auto-refresh on external edits — save in your editor, the view updates within ~250 ms.
"Aktualisiert vor X" badge keeps you honest about how stale the open file is.
Mermaid syntax errors surface as a `` inside the affected diagram container — one bad batch never ruins the whole brew.

Install

winget — recommended

winget install CloudBrew.HopsMD

This 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.

Manual download

For users who do not (yet) have winget, or who prefer downloading the installer directly: grab it from the latest GitHub Release.

HopsMD__x64-setup.exe — NSIS, smaller, per-machine
HopsMD__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.

Updates

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.

Tech stack

Layer	Choice
Shell	Tauri v2 (Rust) — minimal: filesystem bridge only
UI	Angular 21 — standalone components, signals everywhere
Markdown	`marked` with a custom renderer
Diagrams	`mermaid` v11, lazy-loaded
Sanitizer	`DOMPurify` (output then re-trusted for Angular's `[innerHTML]`)
Watcher	`notify-debouncer-mini` — 250 ms debounce
Installer	NSIS + MSI (WiX 3) via `cargo tauri build`
Updater	`tauri-plugin-updater` + ed25519 signatures (feature-gated)

Project layout

HopsMD/
├── src/                  # Angular workspace (the Schankraum / tap room)
│   └── app/
│       ├── services/     # MarkdownStructure, MarkdownParser, MermaidRender, Updater
│       ├── components/   # FileTree, MarkdownView, BreweryToolbar
│       ├── core/         # tauri-bridge, path-utils
│       └── models/
├── src-tauri/            # Tauri / Rust shell (the Braukessel / brew kettle)
│   ├── src/commands/     # recipe_book.rs (file tree + read), watcher.rs
│   ├── capabilities/
│   └── tauri.conf.json
├── winget/               # winget-pkgs manifest templates
├── .github/workflows/    # release.yml + winget.yml
└── docs/RELEASE.md       # human runbook

Local development

Prerequisites: Node 20+, Rust 1.78+, the platform Tauri toolchain (see ).

npm install
npm run tauri:dev   # spins up Angular dev server on :3300 + Tauri shell

Standalone Angular dev (no shell, for fast UI iteration):

npm start           # serves on http://localhost:3300

Production build:

npm run tauri:build
# → src-tauri/target/release/bundle/nsis/HopsMD__x64-setup.exe
# → src-tauri/target/release/bundle/msi/HopsMD__x64_en-US.msi

Brewing glossary

A 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

Contributing

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.