Spec Viewer

A clean, modern documentation viewer for Markdown files. Perfect for software specifications, technical documentation, and project wikis.

Features

Navigation & Structure

• Collapsible folder sections - Organize docs by category
• Natural sorting - Files with numeric prefixes (1.0, 1.1, 2.0, 3.1, 3.2) sort correctly
• Smart ordering - Semantic versioning and numeric prefixes handled intelligently

Top Navigation Bar

• Logo/branding - Customizable site title
• Section dropdowns - Quick access to document categories
• Search box - Fast full-text search across all docs
• Dark/light mode toggle - Persistent theme preference

Search

• Instant search - Search across all document titles and content
• Keyboard shortcut - Press / to focus the search box
• Smart results - Shows document title and context snippet
• ESC to close - Quick dismissal of search results

Content Display

• Clean typography - Optimized for readability
• Syntax highlighting - Code blocks with highlight.js
• Table of contents - Right-side TOC with "In This Article" header
• Scroll spy - TOC highlights current section as you scroll
• Nested subsections - Properly indented TOC hierarchy

Better Tables

• Bordered tables - Clean, professional appearance
• Alternating rows - Subtle zebra striping for readability
• Hover effects - Interactive table rows
• Proper spacing - Optimized padding and alignment

Doc Navigation

• Previous/Next links - Navigate sequentially through docs
• Smart ordering - Based on sidebar organization
• Clear labels - Shows document titles for context

Customization

• Edit links - "Edit this page" button at bottom of each doc
• Configurable source directory - Point to any docs folder
• Brand colors - Easy CSS customization

Quick Start

1. Clone the repo

git clone https://github.com/adamdaigian/spec-viewer.git
cd spec-viewer

2. Configure your docs directory

Set the DOCS_DIR environment variable to point to your documentation folder:

export DOCS_DIR=/path/to/your/docs

Or create a .env file:

DOCS_DIR=/path/to/your/docs

3. Start the server

npm install
npm start

Or use the convenient start script:

chmod +x start.sh
./start.sh

4. Open in browser

Navigate to http://localhost:3334

Configuration

Environment Variables

• DOCS_DIR - Path to your documentation directory (required)
• PORT - Server port (default: 3334)

Folder Structure

The viewer automatically scans your docs directory and organizes files:

docs/
├── README.md              # Shows in "Overview" section
├── MASTERSPEC.md          # Priority ordering
├── docs/                  # Folder becomes "Docs" section
│   ├── 1.0-intro.md      # Natural sorting: 1.0 < 1.1 < 2.0
│   ├── 1.1-setup.md
│   └── 2.0-advanced.md
└── guides/                # Folder becomes "Guides" section
    ├── quick-start.md
    └── deployment.md

Customization

Change Branding

Edit index.html and update the logo/title:

<a href="#" class="nav-logo">△ Your Project Name</a>

Customize Colors

Edit the CSS variables in index.html:

:root {
  --accent-color: #5A7B8F;  /* Primary brand color */
  --accent-hover: #2C4A5A;  /* Hover state */
  /* ... more variables */
}

Exclude Directories

Edit server.mjs and update the EXCLUDE_DIRS array:

const EXCLUDE_DIRS = ['node_modules', '.git', 'drafts'];

Design Inspiration

Inspired by GitHub Spec Kit - a beautiful docs viewer with clean navigation and modern UX.

Technology

• Zero dependencies for the viewer (just vanilla JS)
• Node.js for the server
• marked.js for Markdown parsing
• highlight.js for syntax highlighting
• No build step - just clone and run

Features Roadmap

• Full-text search with better relevance scoring
• Mobile-responsive hamburger menu
• PDF export for individual docs
• Dark/light code theme sync
• Markdown TOC generation in files
• Multi-language support
• Custom footer links
• Analytics integration

Contributing

Pull requests welcome! Please:

1. Test your changes locally
2. Keep the zero-dependency viewer approach
3. Maintain compatibility with existing doc structures

License

MIT License - see LICENSE file

Credits

Created by Adam Daigian

Originally built for Northstar documentation.