asdm-docs-viewer

A lightweight, self-hosted documentation viewer for browsing Markdown-based docs directories in the browser. Built with Express + marked + highlight.js, with a responsive mobile UI, shareable URLs, and persistent tree state.

Features

• Sidebar file tree with collapse/expand, persisted per-browser via localStorage
• Markdown rendering with GitHub-flavored markdown, syntax-highlighted code blocks, images, tables, blockquotes
• URL hash routing — shareable deep links (/#/path/to/file.md) so others land on the exact document
• Mobile responsive — hamburger menu, slide-out sidebar, auto-close on file select, wrapped code blocks (no horizontal page overflow)
• SVG file-type icons (folder / markdown / image / code / generic), no emoji, colored by type
• Tree connector lines and visual differentiation between expanded/collapsed directories
• Forward/back history via hashchange events
• CLI — point at any docs directory, choose port/host, auto-open browser

Install

npm install -g @leansoftx/asdm-docs-viewer

Usage

# Point at a directory of Markdown docs
asdm-docs-viewer ./docs

# Choose port + auto-open browser
asdm-docs-viewer ~/projects/my-repo/docs --port 8080 --open

# Use env vars instead of args
DOCS_ROOT=./docs PORT=8080 asdm-docs-viewer

Then open http://localhost:5060 (or the port you chose). Shareable URLs look like:

http://localhost:5060/#/path/to/file.md

CLI reference

asdm-docs-viewer [path-to-docs] [options]

Arguments:
  path-to-docs     Path to the directory containing Markdown docs.
                   Defaults to $DOCS_ROOT or ./docs.

Options:
  --port <n>       HTTP port (default: 5060, or $PORT)
  --host <addr>    Bind address (default: 0.0.0.0, or $HOST)
  --open           Open the browser after start
  --help, -h       Show help
  --version, -v    Print version

Environment:
  DOCS_ROOT         Same as the positional path argument
  PORT              Same as --port
  HOST              Same as --host

Develop

git clone [email protected]:asdm-ai/asdm-docs-viewer.git
cd asdm-docs-viewer
npm install
npm run dev -- --docs ./path/to/docs

Tech stack

• Runtime: Node.js (>= 18)
• Server: Express
• Markdown: marked
• Syntax highlight: highlight.js
• Frontend: vanilla HTML/CSS/JS (no bundler, no framework)

Roadmap

• [ ] Dark mode theme toggle
• [ ] Optional .docs-viewer.json for per-repo customization (title, ignored globs, default expansion)
• [ ] Inline-bundle client (esbuild) for single-file distribution
• [ ] Optional Node SEA single-executable binary

Not in scope

• Multi-root serving (serving multiple docs directories from one instance)
• Authentication / access control
• Full-text search across document bodies (filename filter only for now)

License

MIT — see LICENSE.