@sullux/markdown-docs

A zero-dependency, local-first static documentation website generator compiling GitBook-style Markdown documentation folders into fast, responsive, searchable HTML websites.

Built on @sullux/markdown-compiler and @sullux/markdown-html, @sullux/markdown-docs operates as both a standalone CLI application and a Node.js library.

Core Features

• GitBook SUMMARY.md Support: Automatically parses SUMMARY.md navigation lists and ## Section headers into sidebar navigation menus (with directory auto-discovery fallback if SUMMARY.md is omitted).
• Zero Dependencies: Pure Vanilla JS implementation using Node.js built-ins.
• Declarative Site Configuration (docs.yaml): Comprehensive YAML configuration file support for logos, themes, external links, favicons, and base URLs.
• Dual Light/Dark Branding: Supports dual logos (logo.light, logo.dark) and dual color schemes with native OS system dark mode detection and client-side manual toggle persistence.
• Client-Side Search: Auto-generates a lightweight JSON search index and embedded client-side search UI.
• Responsive 3-Column Layout: Sticky header with top search bar, left navigation sidebar, center content stream, and right page outline (TOC) with responsive slide-in drawers for mobile.
• Rich Component Support: Supports code syntax highlighting, callout boxes (> [!NOTE], {% hint %}), GFM tables, and custom image dimensions.
• Static Asset Copying: Automatically copies non-Markdown assets (images, SVGs, PDFs) directly to the output directory.

CLI Usage

# Generate site using default docs.yaml configuration in ./docs
markdown-docs -i ./docs -o ./_site

# Build with a custom base URL for CI/CD environments
markdown-docs -i ./docs -o ./_site -b "/my-app-docs/"

CLI Options

| Flag | Long Flag | Description | Default | | :--- | :--- | :--- | :--- | | -i | --input | Path to input Markdown docs directory | Current working directory | | -o | --output | Path to output build directory | <input>/_site | | -b | --base-url | Base URL prefix for links and deployment | "" | | -t | --title | Site title override (overrides docs.yaml) | title in docs.yaml | | -c | --config | Custom path to config file | <input>/docs.yaml | | -h | --help | Display CLI help menu | |

Site Configuration (docs.yaml)

You can configure your documentation site by placing a docs.yaml (or docs.yml / docs.json) file in your input documentation directory.

Example docs.yaml

# Site Title (Optional: omit or leave empty for logo-only headers)
title: "BucketDB"

# Output directory (Optional: can also be passed via CLI)
output: "_site"

# Base URL prefix (Optional: useful for GitHub Pages or subdirectory hosting)
baseUrl: "/docs"

# Brand Logo (Supports single path/SVG, or dual light/dark images)
logo:
  light: "assets/logo-light.svg"
  dark: "assets/logo-dark.svg"

# Favicon Asset Path or URL
favicon: "assets/favicon.ico"

# External Header Navigation Links
links:
  - title: "GitHub"
    url: "https://github.com/sullux/coms"
  - title: "API Spec"
    url: "https://api.example.com"

# Theme Color Overrides
theme:
  light:
    bg: "#ffffff"
    accent: "#2563eb"
    codeBg: "#f8fafc"
    codeText: "#0f172a"
  dark:
    bg: "#121316"
    accent: "#3b82f6"
    codeBg: "#0a0b0e"
    codeText: "#f3f4f6"

Configuration Options Reference

| Property | Type | Description | Default | | :--- | :--- | :--- | :--- | | title | string | Product or site name displayed in header & <title> tag. Leave empty ("") or omit when using a logo image containing the product name. | "" | | output | string | Relative or absolute path to output build directory. | <input>/_site | | baseUrl | string | Base URL path prefix for hosting in subdirectories. | "" | | logo | string \| object | Asset path/SVG string, or { light: "...", dark: "..." } object for automatic theme switching. | "" | | favicon | string | Asset path or URL to icon file. | Default book emoji (📚) | | links | array | Header external links array [{ title: "...", url: "..." }]. | [] | | theme.light | object | Light theme color overrides (bg, accent, codeBg, codeText). | Built-in light colors | | theme.dark | object | Dark theme color overrides (bg, accent, codeBg, codeText). | Built-in dark colors |

Programmatic API Usage

const { generateSite } = require('@sullux/markdown-docs')

const result = generateSite({
  input: './docs',
  output: './dist',
  baseUrl: '/docs',
})

console.log(`Generated ${result.pageCount} pages at ${result.output}`)

Running Unit Tests

yarn test