MD Star

MD Star is an open-source Markdown viewer and editor for macOS and Linux. It ships a native Tauri desktop app and a terminal-first md command from the same Rust binary, backed by a shared parser and renderer stack.

Status

This project is pre-1.0 and preparing for its first public GitHub release.

Current implementation:

• shared semantic Markdown core with parser diagnostics,
• high-fidelity terminal rendering with tables, code blocks, and Mermaid text diagrams,
• interactive ratatui viewer with split source edit mode and live preview,
• Tauri desktop app with open/save/reload/watch, rendered preview, outline, Mermaid diagrams, and debounced autosave with unsaved-close guard rails,
• macOS file associations for .md, .markdown, and .txt,
• release workflow for macOS, Linux, and Windows artifacts.

Remaining release gates:

• validate macOS "Open With" from an installed .app,
• validate Linux package output on GitHub Actions,
• set the final GitHub repository path for install.sh,
• add signed/notarized macOS release support when certificates are available.

Workspace Layout

.
+-- Cargo.toml
+-- crates/
|   +-- mdstar-core/             parser, semantic IR, diagnostics
|   +-- mdstar-render-terminal/  terminal renderer and Mermaid text output
|   +-- mdstar-render-html/      HTML renderer for desktop/system previews
|   +-- mdstar-app/              active `md` binary: CLI + Tauri desktop app
|   +-- mdstar-cli/              legacy standalone CLI crate, not in workspace
|   `-- mdstar-ffi/              C ABI bridge for system integration adapters
+-- docs/                          project docs and static web page
+-- tests/fixtures/                shared regression fixtures
`-- install.sh                     release installer for CLI archives

Quick Start

cargo test --workspace --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo run -p mdstar-app -- tests/fixtures/sample.md --no-tui --plain
cargo run -p mdstar-app -- tests/fixtures/sample.md
cargo run -p mdstar-app -- --app

Desktop Build

Plain Cargo builds the md binary only:

cargo build --release -p mdstar-app

Installer and app bundles are generated by Tauri:

cd crates/mdstar-app
cargo tauri build
cargo tauri build --bundles dmg

On macOS the DMG is written under:

target/release/bundle/dmg/

After installing the macOS app, link the bundled command-line executable:

./install.sh --link-app
md --help

CLI UX

Default mode (TTY): ratatui interactive viewer
  - q: quit
  - e: enter split edit mode
  - r: reload file
  - j/k or arrows: scroll
  - PgUp/PgDn, g/G: jump

Edit mode:
  - type directly in the source pane
  - live preview updates beside it
  - Esc: close edit mode and auto-save
  - Ctrl+S: save
  - Ctrl+Q: quit

Non-TUI mode:
  - use --plain or --no-tui for direct terminal output
  - use --ascii-mermaid when Unicode diagram output is not desired
  - use --pager "less -R" or --no-pager to control paging

Architecture

Markdown input
   |
   v
mdstar-core
   |
   +--> mdstar-render-terminal --> md CLI / ratatui viewer
   |
   +--> mdstar-render-html -----> Tauri desktop preview
   |
   `--> mdstar-ffi -------------> future Quick Look/system adapters

Documentation

• Documentation index
• Architecture
• Project plan
• Milestone status
• Release checklist
• Static project page

Open Source Baseline

• dual licensed under MIT or Apache-2.0,
• issue templates and pull request template included,
• CI checks format, clippy, and tests,
• release workflow creates draft GitHub releases from version tags.