Markdown Viewer

A beautiful, minimalist markdown viewer CLI that renders your documents in a clean, book-like style with an interactive table of contents.

Features

• Beautiful typography — Serif fonts with generous line-height for comfortable reading, just like a book
• Interactive table of contents — Collapsible sidebar that expands on hover, with click-to-navigate and scroll tracking
• Syntax highlighting — Code blocks with GitHub-style highlighting for 190+ languages via highlight.js
• Mermaid diagrams — Render flowcharts, sequence diagrams, and more from fenced code blocks
• Multi-file tabs — Open multiple markdown files with tab deduplication
• Relative link navigation — Click relative markdown links to open them in a new tab
• Instant launch — CLI exits immediately, leaving the viewer window open
• Lightweight — Minimal dependencies, fast startup

Installation

Prerequisites

• Bun v1.0 or later

From source

git clone https://github.com/yourusername/markdown-viewer.git
cd markdown-viewer
bun install
bun run build
bun link

Usage

# View a single file
mdview README.md

# View multiple files (opens in tabs)
mdview doc1.md doc2.md doc3.md

# Alternative command name
markdown-viewer README.md

# Show help
mdview --help

# Show version
mdview --version

Keyboard shortcuts

Shortcut	Action
Cmd/Ctrl + W	Close current tab
Cmd/Ctrl + Q	Quit application

Development

Project structure

markdown-viewer/
├── src/
│   ├── cli/                  # CLI entry point and argument parsing
│   │   ├── index.ts
│   │   └── args-parser.ts
│   ├── domain/               # Pure business logic (no framework deps)
│   │   ├── types.ts
│   │   ├── file-loader.ts
│   │   └── toc-extractor.ts
│   ├── electron/             # Main process
│   │   ├── main.ts
│   │   ├── preload.ts
│   │   └── ipc-handlers.ts
│   └── renderer/             # Browser-side UI
│       ├── index.html
│       ├── styles.css
│       └── scripts/
│           ├── app.ts
│           ├── markdown-renderer.ts
│           ├── toc-renderer.ts
│           └── tabs-manager.ts
├── tests/                    # Unit tests
├── assets/                   # App icons (icns, png, svg)
├── package.json
├── tsconfig.json
└── tailwind.config.js

Build commands

bun run build       # Full build (TypeScript + Bun bundling + Tailwind + HTML/assets copy)
bun run dev         # Build and launch Electron app
bun run start       # Launch Electron app (requires prior build)
bun run clean       # Remove dist/ directory

Individual build steps

bun run build:main        # TypeScript compilation (main process)
bun run build:preload     # Bundle preload script (CJS format for Electron)
bun run build:renderer    # Bundle renderer scripts (browser target)
bun run build:tailwind    # Compile Tailwind CSS
bun run copy:html         # Copy HTML to dist
bun run copy:assets       # Copy assets to dist

Running tests

bun test                              # Run all tests
bun test --watch                      # Watch mode
bun test tests/toc-extractor.test.ts  # Run specific test file

Architecture

The project follows Clean Architecture with strict layer separation:

CLI Layer (src/cli/)
  │  Parses args, spawns detached Electron process
  ▼
Electron Main (src/electron/)
  │  Window creation, IPC handlers, file caching
  ▼
Domain (src/domain/)
  │  Pure business logic — file loading, TOC extraction, types
  ▼
Renderer (src/renderer/)
     Vanilla TypeScript UI — tabs, markdown rendering, TOC sidebar

• Domain layer has zero framework dependencies — pure functions and types only
• Context isolation is enabled — renderer communicates with main process via typed IPC channels
• ESM modules throughout (except preload, which must be CJS per Electron requirements)
• All source files are kept under 150 lines for readability

Tech stack

Technology	Purpose
Bun	Runtime, bundler & package manager
Electron	Desktop window
TypeScript	Type safety (strict mode)
Tailwind CSS	Styling + Typography plugin
marked	Markdown parsing
highlight.js	Syntax highlighting
Mermaid	Diagram rendering

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Guidelines

• Follow the existing code style
• Keep files under 150 lines
• Add tests for new functionality
• Update documentation as needed

License

This project is licensed under the MIT License — see the LICENSE file for details.

Acknowledgments

• Typography inspired by iA Writer
• Syntax highlighting theme based on GitHub Light