Zero-dependency, standalone HTTP server & browser document viewer for Markdown (.md), MDX (.mdx), HTML (.html), KaTeX formulas, Mermaid diagrams, and interactive inline comments.

✨ Key Features

🚀 Zero-Dependency Backend: Runs on Node.js built-in modules (http, fs, path, crypto).
📁 Zero-Config Auto Discovery: Automatically discovers top-level documentation folders in any repository when executed via NPX.
📝 Multi-Format Support:
- Markdown (.md): Full GFM support, task lists, tables, auto-generated Table of Contents (TOC).
- MDX (.mdx): Client-side transpilation via Babel & React with built-in UI components (<Callout>, <Card>, <Badge>, <Button>).
- HTML (.html, .htm): Sanitized inline HTML rendering via DOMPurify.
📊 Rich Visuals & Formulas:
- Mermaid Diagrams: Interactive rendering with dark/light theme switching and lightbox zoom modal.
- KaTeX: Fast math formula rendering ($\LaTeX$).
💬 In-House Inline Comments: Highlight text or blocks to add, navigate, and resolve discussion threads without external services.
🔍 Client-Side Search: Instant fuzzy search across document names and paths.
🎨 Theme & Layout Control: Sleek Dark/Light mode toggle, resizable panels, and responsive mobile drawer.
🔐 Security & Protection: Built-in Path Traversal protection and optional HTTP Basic Auth.

⚡ Quick Start (NPX)

Run @thiennq/docs-viewer (or docs-viewer) instantly inside any repository without installing anything globally:

# Run in current directory on default port 8888
npx @thiennq/docs-viewer

# Run on a custom port (e.g., 9000)
npx @thiennq/docs-viewer 9000

# Run on a specific target directory
npx @thiennq/docs-viewer --port 9000 --dir ./docs

Open your browser at http://localhost:8888.

💡 Tip: If no configuration file is present, docs-viewer will automatically scan and display top-level directories in your project.

🛠️ Configuration (`docs-viewer.json`)

You can customize branding, directory mappings, and quicklinks by adding a docs-viewer.json file to your repository root:

{
  "branding": {
    "title": "My Technical Docs",
    "logoIcon": "⚡",
    "logoText": "Tech Docs"
  },
  "directories": [
    { "name": "Architecture", "path": "docs/architecture" },
    { "name": "API Specification", "path": "docs/api" },
    { "name": "User Guides", "path": "docs/guides" }
  ],
  "quicklinks": [
    {
      "name": "System Architecture",
      "urlPath": "/docs/Architecture/overview.md"
    },
    {
      "name": "Getting Started Guide",
      "urlPath": "/docs/User Guides/getting-started.md"
    }
  ]
}

All fields are optional. If directories is omitted, auto-discovery will automatically find your project folders.

🔒 Security & Authentication

HTTP Basic Auth Protection

To protect sensitive internal documentation in staging/production environments, set the following environment variables when starting the server:

BASIC_AUTH_USER=admin BASIC_AUTH_PASS=supersecret npx docs-viewer 8888

🚀 Installation

You can install @thiennq/docs-viewer directly from GitHub or NPM into any project's dependencies:

# Via GitHub shorthand (Recommended):
npm install github:thiennq/docs-viewer

# Via HTTPS:
npm install git+https://github.com/thiennq/docs-viewer.git

# Via SSH Key:
npm install git+ssh://git@github.com:thiennq/docs-viewer.git