@sullux/markdown-docs 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charles Sullivan <charles@sullux.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# @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 into sidebar navigation menus (with auto-discovery fallback if `SUMMARY.md` is omitted).
+* **Zero Dependencies:** Pure Vanilla JS implementation with zero external packages.
+* **Client-Side Search:** Auto-generates a lightweight JSON search index and embedded client-side search UI.
+* **Responsive Layout:** Clean GitBook-inspired UI with collapsible sidebar navigation, dark/light theme toggle, and mobile support.
+* **Rich Component Support:** Supports all `@sullux/markdown-html` features including code syntax highlighting, callout boxes (`> [!NOTE]`, `{% hint %}`), GFM tables, and custom image dimensions.
+* **Static Asset Copying:** Automatically copies non-markdown assets (PNGs, SVGs, PDFs) directly to the output directory.
+
+## Installation & CLI Usage
+
+```bash
+# Global installation or via npx
+npm install -g @sullux/markdown-docs
+
+# Generate site from a docs directory
+markdown-docs -i ./docs -o ./_site -t "Project Documentation"
+```
+
+### CLI Options
+
+| Flag | Long Flag | Description | Default |
+| :--- | :--- | :--- | :--- |
+| `-i` | `--input` | Input Markdown docs directory | Current working directory |
+| `-o` | `--output` | Output directory | `<input>/_site` |
+| `-t` | `--title` | Documentation site title | Directory name |
+| | `--baseUrl` | Base URL prefix for links | `""` |
+| `-h` | `--help` | Display CLI help menu | |
+
+## Programmatic API Usage
+
+```javascript
+const { generateSite } = require('@sullux/markdown-docs')
+
+const result = generateSite({
+  input: './docs',
+  output: './dist',
+  title: 'Sullux API Docs',
+})
+
+console.log(`Generated ${result.pageCount} pages at ${result.output}`)
+```
+
+## Folder Topography
+
+```
+packages/markdown-docs/
+├── bin/
+│   └── cli.js            # Executable CLI entrypoint
+├── lib/
+│   ├── config.js         # Option and CLI argument parser
+│   ├── summary.js        # SUMMARY.md parser and directory scanner
+│   ├── layout.js         # Responsive HTML page template generator
+│   ├── theme.js          # Embedded GitBook CSS styles
+│   ├── search.js         # Client-side search index and JS script
+│   ├── assets.js         # Static asset copy utility
+│   └── site.js           # Site generation coordinator
+├── index.js              # Package API entrypoint
+└── package.json          # Package manifest
+```
+
+## Running Unit Tests
+
+```bash
+yarn test
+```

package/bin/cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+const { parseArgs } = require('../lib/config')
+const { generateSite } = require('../lib/site')
+
+const printHelp = () => {
+  console.log(`
+Usage: markdown-docs [options]
+
+Options:
+  -i, --input <dir>      Path to input Markdown docs directory (default: CWD)
+  -o, --output <dir>     Path to output directory (default: <input>/_site)
+  -t, --title <title>    Site title
+  --baseUrl <url>        Base URL prefix for links
+  -h, --help             Show help documentation
+`)
+}
+
+const main = () => {
+  const args = process.argv.slice(2)
+  const options = parseArgs(args)
+
+  if (options.help) {
+    printHelp()
+    process.exit(0)
+  }
+
+  try {
+    const res = generateSite(options)
+    console.log(`Successfully generated ${res.pageCount} documentation pages -> ${res.output}`)
+  } catch (err) {
+    console.error(`Error generating docs: ${err.message}`)
+    process.exit(1)
+  }
+}
+
+main()

package/index.js

@@ -0,0 +1,4 @@
+const { generateSite } = require('./lib/site')
+const { normalizeConfig } = require('./lib/config')
+
+module.exports = { generateSite, generateDocs: generateSite, normalizeConfig }

package/lib/assets.js

@@ -0,0 +1,22 @@
+const fs = require('node:fs')
+const path = require('node:path')
+
+const copyAssets = (srcDir, destDir) => {
+  if (!fs.existsSync(srcDir)) return
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true })
+
+  for (const entry of entries) {
+    if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === '_site') continue
+    const srcPath = path.join(srcDir, entry.name)
+    const destPath = path.join(destDir, entry.name)
+
+    if (entry.isDirectory()) {
+      copyAssets(srcPath, destPath)
+    } else if (entry.isFile() && !entry.name.endsWith('.md')) {
+      if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true })
+      fs.copyFileSync(srcPath, destPath)
+    }
+  }
+}
+
+module.exports = { copyAssets }

package/lib/config.js

@@ -0,0 +1,34 @@
+const path = require('node:path')
+
+const parseArgs = (args = []) => {
+  const options = {}
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '-i' || arg === '--input') {
+      options.input = args[++i]
+    } else if (arg === '-o' || arg === '--output') {
+      options.output = args[++i]
+    } else if (arg === '-t' || arg === '--title') {
+      options.title = args[++i]
+    } else if (arg === '--logo') {
+      options.logo = args[++i]
+    } else if (arg === '--baseUrl') {
+      options.baseUrl = args[++i]
+    } else if (arg === '-h' || arg === '--help') {
+      options.help = true
+    }
+  }
+  return options
+}
+
+const normalizeConfig = (opts = {}) => {
+  const input = path.resolve(opts.input || process.cwd())
+  const output = path.resolve(opts.output || path.join(input, '_site'))
+  const title = opts.title || path.basename(input)
+  const baseUrl = opts.baseUrl || ''
+  const logo = opts.logo || ''
+
+  return { input, output, title, baseUrl, logo }
+}
+
+module.exports = { parseArgs, normalizeConfig }

package/lib/layout.js

@@ -0,0 +1,53 @@
+const { getCss } = require('./theme')
+const { getSearchScript } = require('./search')
+
+const renderNavItems = (items, currentHref, baseUrl = '') => {
+  if (!items || items.length === 0) return ''
+  return `<ul class="nav-list">\n` + items.map((item) => {
+    const isActive = item.href === currentHref ? ' active' : ''
+    const itemHref = item.href ? `${baseUrl}${item.href.replace(/\.md$/, '.html')}` : '#'
+    const subNav = item.children ? renderNavItems(item.children, currentHref, baseUrl) : ''
+    return `<li class="nav-item">
+      <a href="${itemHref}" class="nav-link${isActive}">${item.title}</a>
+      ${subNav}
+    </li>\n`
+  }).join('') + `</ul>\n`
+}
+
+const renderPageLayout = ({ title, navTree, contentHtml, currentHref, baseUrl = '' }) => {
+  const sidebarNav = renderNavItems(navTree, currentHref, baseUrl)
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>${title}</title>
+  <style>${getCss()}</style>
+</head>
+<body>
+  <aside class="app-sidebar">
+    <a href="${baseUrl}index.html" class="app-title">${title}</a>
+    <div class="search-box">
+      <input type="text" id="doc-search" class="search-input" placeholder="Search docs..." />
+      <div id="search-results" class="search-results"></div>
+    </div>
+    <nav class="app-nav">
+      ${sidebarNav}
+    </nav>
+  </aside>
+  <main class="app-main">
+    <header class="app-header">
+      <span class="header-title">${title}</span>
+      <button class="theme-toggle" onclick="document.body.toggleAttribute('data-theme', document.body.hasAttribute('data-theme') ? '' : 'dark')">Theme</button>
+    </header>
+    <article class="app-content">
+      ${contentHtml}
+    </article>
+  </main>
+  ${getSearchScript()}
+</body>
+</html>`
+}
+
+module.exports = { renderPageLayout }

package/lib/search.js

@@ -0,0 +1,40 @@
+const getSearchScript = () => `
+<script>
+(function() {
+  var searchInput = document.getElementById('doc-search');
+  var resultsContainer = document.getElementById('search-results');
+  if (!searchInput || !resultsContainer) return;
+
+  var index = [];
+  fetch('search-index.json')
+    .then(function(res) { return res.json(); })
+    .then(function(data) { index = data; })
+    .catch(function() {});
+
+  searchInput.addEventListener('input', function(e) {
+    var query = e.target.value.toLowerCase().trim();
+    if (!query) {
+      resultsContainer.style.display = 'none';
+      resultsContainer.innerHTML = '';
+      return;
+    }
+
+    var matches = index.filter(function(item) {
+      return item.title.toLowerCase().indexOf(query) !== -1 ||
+             item.content.toLowerCase().indexOf(query) !== -1;
+    }).slice(0, 8);
+
+    if (matches.length === 0) {
+      resultsContainer.innerHTML = '<div class="search-item">No results found</div>';
+    } else {
+      resultsContainer.innerHTML = matches.map(function(item) {
+        return '<a href="' + item.href + '" class="search-item"><strong>' + item.title + '</strong></a>';
+      }).join('');
+    }
+    resultsContainer.style.display = 'block';
+  });
+})();
+</script>
+`
+
+module.exports = { getSearchScript }

package/lib/site.js

@@ -0,0 +1,73 @@
+const fs = require('node:fs')
+const path = require('node:path')
+const { markdownToHtml } = require('@sullux/markdown-html')
+const { normalizeConfig } = require('./config')
+const { getNavigationTree } = require('./summary')
+const { renderPageLayout } = require('./layout')
+const { copyAssets } = require('./assets')
+
+const collectMarkdownFiles = (dir, rootDir = dir) => {
+  const files = []
+  const entries = fs.readdirSync(dir, { withFileTypes: true })
+
+  for (const entry of entries) {
+    if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === '_site') continue
+    const fullPath = path.join(dir, entry.name)
+
+    if (entry.isDirectory()) {
+      files.push(...collectMarkdownFiles(fullPath, rootDir))
+    } else if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== 'SUMMARY.md') {
+      const relPath = path.relative(rootDir, fullPath)
+      files.push({ fullPath, relPath })
+    }
+  }
+
+  return files
+}
+
+const generateSite = (options = {}) => {
+  const config = normalizeConfig(options)
+  if (!fs.existsSync(config.input)) {
+    throw new Error(`Input directory does not exist: ${config.input}`)
+  }
+
+  fs.mkdirSync(config.output, { recursive: true })
+  const navTree = getNavigationTree(config.input)
+  const mdFiles = collectMarkdownFiles(config.input)
+  const searchIndex = []
+
+  for (const file of mdFiles) {
+    const rawMd = fs.readFileSync(file.fullPath, 'utf8')
+    const contentHtml = markdownToHtml(rawMd)
+
+    const relHtmlPath = file.relPath.replace(/\.md$/, '.html')
+    const outHtmlPath = path.join(config.output, relHtmlPath)
+
+    fs.mkdirSync(path.dirname(outHtmlPath), { recursive: true })
+
+    const pageTitle = `${file.relPath.replace(/\.md$/, '')} - ${config.title}`
+    const fullHtml = renderPageLayout({
+      title: pageTitle,
+      navTree,
+      contentHtml,
+      currentHref: file.relPath,
+      baseUrl: config.baseUrl,
+    })
+
+    fs.writeFileSync(outHtmlPath, fullHtml, 'utf8')
+
+    const plainText = rawMd.replace(/[#*`_\[\]()\-]/g, ' ').replace(/\s+/g, ' ').trim()
+    searchIndex.push({
+      title: file.relPath.replace(/\.md$/, ''),
+      href: relHtmlPath,
+      content: plainText.slice(0, 300),
+    })
+  }
+
+  fs.writeFileSync(path.join(config.output, 'search-index.json'), JSON.stringify(searchIndex, null, 2))
+  copyAssets(config.input, config.output)
+
+  return { output: config.output, pageCount: mdFiles.length }
+}
+
+module.exports = { generateSite }

package/lib/summary.js

@@ -0,0 +1,57 @@
+const fs = require('node:fs')
+const path = require('node:path')
+const { parse } = require('@sullux/markdown-compiler')
+
+const parseSummaryMd = (content) => {
+  const ast = parse(content)
+  const items = []
+
+  for (const block of ast.blocks) {
+    if (block.type === 'bulletList' || block.type === 'orderedList') {
+      for (const itemNodes of block.items || []) {
+        for (const node of itemNodes) {
+          if (node.type === 'link') {
+            const title = node.children ? node.children.map((c) => c.value || '').join('') : ''
+            items.push({ title, href: node.url, children: [] })
+          }
+        }
+      }
+    }
+  }
+
+  return items
+}
+
+const scanDir = (dir, rootDir = dir) => {
+  const entries = fs.readdirSync(dir, { withFileTypes: true })
+  const items = []
+
+  for (const entry of entries) {
+    if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === '_site') continue
+    const fullPath = path.join(dir, entry.name)
+    const relPath = path.relative(rootDir, fullPath)
+
+    if (entry.isDirectory()) {
+      const children = scanDir(fullPath, rootDir)
+      if (children.length > 0) {
+        items.push({ title: entry.name, href: '', children })
+      }
+    } else if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== 'SUMMARY.md') {
+      const title = entry.name.replace(/\.md$/, '')
+      items.push({ title, href: relPath, children: [] })
+    }
+  }
+
+  return items
+}
+
+const getNavigationTree = (inputDir) => {
+  const summaryPath = path.join(inputDir, 'SUMMARY.md')
+  if (fs.existsSync(summaryPath)) {
+    const content = fs.readFileSync(summaryPath, 'utf8')
+    return parseSummaryMd(content)
+  }
+  return scanDir(inputDir)
+}
+
+module.exports = { parseSummaryMd, scanDir, getNavigationTree }

package/lib/theme.js

@@ -0,0 +1,75 @@
+const getCss = () => `
+:root {
+  --bg-primary: #ffffff;
+  --bg-sidebar: #f7f9fa;
+  --text-primary: #1c1e21;
+  --text-muted: #5c6975;
+  --border-color: #e8ecf0;
+  --accent-color: #3b82f6;
+  --accent-hover: #1d4ed8;
+  --code-bg: #f3f4f6;
+  --callout-info-bg: #eff6ff;
+  --callout-info-border: #3b82f6;
+}
+
+[data-theme="dark"] {
+  --bg-primary: #0f172a;
+  --bg-sidebar: #1e293b;
+  --text-primary: #f8fafc;
+  --text-muted: #94a3b8;
+  --border-color: #334155;
+  --accent-color: #60a5fa;
+  --accent-hover: #93c5fd;
+  --code-bg: #1e293b;
+  --callout-info-bg: #1e3a8a;
+  --callout-info-border: #60a5fa;
+}
+
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; color: var(--text-primary); background: var(--bg-primary); line-height: 1.6; display: flex; min-height: 100vh; }
+
+.app-sidebar { width: 280px; background: var(--bg-sidebar); border-right: 1px solid var(--border-color); padding: 1.5rem; display: flex; flex-direction: column; shrink: 0; }
+.app-title { font-size: 1.25rem; font-weight: 700; margin-bottom: 1rem; color: var(--text-primary); text-decoration: none; display: flex; align-items: center; gap: 0.5rem; }
+.search-box { margin-bottom: 1rem; position: relative; }
+.search-input { width: 100%; padding: 0.5rem 0.75rem; border: 1px solid var(--border-color); border-radius: 6px; background: var(--bg-primary); color: var(--text-primary); }
+.search-results { position: absolute; top: 100%; left: 0; right: 0; background: var(--bg-primary); border: 1px solid var(--border-color); border-radius: 6px; max-height: 250px; overflow-y: auto; z-index: 100; display: none; }
+.search-item { padding: 0.5rem; text-decoration: none; color: var(--text-primary); display: block; border-bottom: 1px solid var(--border-color); }
+.search-item:hover { background: var(--code-bg); }
+
+.nav-list { list-style: none; }
+.nav-item { margin-bottom: 0.25rem; }
+.nav-link { display: block; padding: 0.4rem 0.6rem; color: var(--text-muted); text-decoration: none; border-radius: 4px; font-size: 0.95rem; }
+.nav-link:hover, .nav-link.active { color: var(--accent-color); font-weight: 600; background: var(--code-bg); }
+.nav-sub { list-style: none; padding-left: 1rem; margin-top: 0.25rem; }
+
+.app-main { flex: 1; display: flex; flex-direction: column; overflow-x: hidden; }
+.app-header { padding: 1rem 2rem; border-bottom: 1px solid var(--border-color); display: flex; justify-content: space-between; align-items: center; }
+.app-content { flex: 1; padding: 2rem 3rem; max-width: 900px; }
+.theme-toggle { cursor: pointer; background: none; border: 1px solid var(--border-color); padding: 0.4rem 0.8rem; border-radius: 6px; color: var(--text-primary); }
+
+pre { background: var(--code-bg); padding: 1rem; border-radius: 8px; overflow-x: auto; margin: 1rem 0; font-family: monospace; }
+code { background: var(--code-bg); padding: 0.2rem 0.4rem; border-radius: 4px; font-size: 0.9em; }
+pre code { background: none; padding: 0; }
+
+.callout { border-left: 4px solid var(--callout-info-border); background: var(--callout-info-bg); padding: 1rem; margin: 1rem 0; border-radius: 0 6px 6px 0; }
+.callout-title { font-weight: 700; margin-bottom: 0.5rem; text-transform: uppercase; font-size: 0.85rem; letter-spacing: 0.05em; }
+
+table { width: 100%; border-collapse: collapse; margin: 1rem 0; }
+th, td { border: 1px solid var(--border-color); padding: 0.6rem 0.8rem; text-align: left; }
+th { background: var(--code-bg); }
+
+.hl-kw { color: #d73a49; font-weight: bold; }
+.hl-str { color: #032f62; }
+.hl-num { color: #005cc5; }
+.hl-cmt { color: #6a737d; font-style: italic; }
+.hl-id { color: #6f42c1; }
+.hl-punc { color: #24292e; }
+
+@media (max-width: 768px) {
+  body { flex-direction: column; }
+  .app-sidebar { width: 100%; border-right: none; border-bottom: 1px solid var(--border-color); }
+  .app-content { padding: 1.5rem; }
+}
+`
+
+module.exports = { getCss }

package/lib/toc.js

@@ -0,0 +1,21 @@
+const { slugify } = require('@sullux/markdown-html/lib/markdown-to-html/slugify')
+
+const extractToc = (ast) => {
+  if (!ast || !ast.blocks) return []
+  const usedSlugs = new Set()
+  const toc = []
+
+  for (const block of ast.blocks) {
+    if (block.type === 'header' && (block.level === 2 || block.level === 3)) {
+      const rawText = block.children
+        ? block.children.map((c) => (c.type === 'text' ? c.value : '')).join('')
+        : ''
+      const slug = slugify(rawText, usedSlugs)
+      toc.push({ level: block.level, title: rawText, id: slug })
+    }
+  }
+
+  return toc
+}
+
+module.exports = { extractToc }

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@sullux/markdown-docs",
+  "version": "1.0.0",
+  "description": "A zero-dependency, local-first static documentation site generator compiling GitBook-style Markdown docs.",
+  "main": "./index.js",
+  "bin": {
+    "markdown-docs": "./bin/cli.js"
+  },
+  "author": "Charles Sullivan <charles@sullux.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Sullux/markdown.git",
+    "directory": "packages/markdown-docs"
+  },
+  "bugs": {
+    "url": "https://github.com/Sullux/markdown/issues"
+  },
+  "homepage": "https://github.com/Sullux/markdown/tree/main/packages/markdown-docs#readme",
+  "keywords": [
+    "markdown",
+    "docs",
+    "gitbook",
+    "static-site-generator",
+    "documentation",
+    "compiler"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@sullux/markdown-compiler": "^1.0.0",
+    "@sullux/markdown-html": "^1.0.0"
+  }
+}