dochub 1.0.4 → 2.0.0

package/README.md

@@ -1,52 +1,198 @@
-# DocHub
-
-[![npm dependents](https://badgen.net/npm/dependents/dochub)](https://www.npmjs.com/package/dochub?activeTab=dependents)
-[![install size](https://packagephobia.com/badge?p=dochub)](https://packagephobia.com/result?p=dochub)
-[![Downloads](https://badgen.net/npm/dt/dochub)](https://www.npmjs.com/package/dochub)
-[![NPM Version](https://img.shields.io/npm/v/code-example.svg)](https://www.npmjs.com/package/dochub)
-
-DocHub is a CLI tool for dynamically generating and displaying documentation from Markdown files converted to HTML. It includes real-time updates, search functionality, syntax highlighting, and dark mode support for better readability.
-
-## Features
-
-- **Real-time Updates:** Automatically refreshes content when documentation files are modified.
-- **Search Functionality:** Includes a search bar to filter through documentation content.
-- **Syntax Highlighting:** Uses Highlight.js to format code blocks for better readability.
-- **Dark Mode:** Implements a dark mode theme for improved viewing experience.
-
-## Getting Started
-
-To start using DocHub, follow these steps:
-
-1. **Installation:**
-   - Ensure Node.js is installed on your system.
-
-2. **Initialize Project:**
-   - Run `dochub init [directory]` in your terminal to set up a new DocHub project.
-   - Replace `[directory]` with the path where you want to initialize your documentation project.
-
-3. **Generate Documentation:**
-   - Once initialized, run `dochub serve [directory]` in your terminal.
-   - Replace `[directory]` with the path to your documentation files.
-
-4. **View Documentation:**
-   - Open a web browser and navigate to `http://localhost:3000`.
-   - The sidebar lists different sections of your documentation.
-   - Use the search bar to find specific topics within the documentation.
-
-## Project Structure
-
-The project structure includes:
-
-- **HTML and CSS:** Main structure and styling managed using HTML and Tailwind CSS.
-- **JavaScript (Client-side):** Handles dynamic content updates, event handling, and integration with external libraries like Socket.IO and Highlight.js.
-- **Socket.IO:** Facilitates real-time communication to update documentation on file changes.
-- **Markdown to HTML Conversion:** Converts Markdown content fetched from the server-side into HTML for rendering.
-
-## Getting Help
-
-If you encounter any issues or have questions about using DocHub, feel free to reach out via [GitHub Issues](https://github.com/tyler-Github/dochub/issues).
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
+# DocHub
+
+<p>
+  <a href="https://www.npmjs.com/package/dochub"><img src="https://img.shields.io/npm/v/dochub?style=flat&label=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/dochub"><img src="https://img.shields.io/npm/dt/dochub?style=flat&label=downloads" alt="npm downloads"></a>
+  <a href="https://packagephobia.com/result?p=dochub"><img src="https://packagephobia.com/badge?p=dochub" alt="install size"></a>
+  <a href="https://github.com/tyler-Github/dochub/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat" alt="license"></a>
+</p>
+
+Write Markdown. Ship beautiful documentation.
+
+DocHub is a zero-config documentation tool that turns a folder of Markdown files into a modern, searchable, themeable documentation site. Use it as a live-reload dev server during writing, then export a fully self-contained static site for deployment.
+
+---
+
+## Features
+
+| | |
+|---|---|
+| **Live preview** | Dev server with instant reload on file changes |
+| **Static export** | Build a portable HTML site with clean URLs (`/guide`, `/api/auth`) |
+| **Full-text search** | Client-side search across all pages with relevance scoring |
+| **Dark mode** | Light/dark toggle with persistent preference |
+| **Syntax highlighting** | 190+ languages via Highlight.js |
+| **File-tree sidebar** | Auto-generated navigation from your folder structure |
+| **Responsive** | Works on desktop, tablet, and mobile |
+| **Self-contained** | Zero external CDN dependencies in the output |
+
+## Install
+
+```bash
+npm install -g dochub
+```
+
+## Quick start
+
+```bash
+# Scaffold a new project
+dochub init my-docs
+
+# Start writing — open http://localhost:3000
+cd my-docs && dochub serve
+
+# Build for production
+dochub build
+```
+
+## Project structure
+
+```
+my-docs/
+├── markdown/              # Your content — add .md files here
+│   ├── README.md          # Home page (/)
+│   ├── guide.md           # /guide
+│   ├── api/
+│   │   ├── README.md      # /api
+│   │   └── authentication # /api/authentication
+│   └── deployment/
+│       └── README.md      # /deployment
+└── dochub.config.js       # Site configuration
+```
+
+Every folder becomes a collapsible sidebar section. `README.md` inside a folder becomes the folder's index page at a clean URL (`/api` not `/api/readme`).
+
+## Commands
+
+### `dochub init [directory]`
+
+Scaffolds a new documentation project with a `markdown/` folder containing starter pages and a `dochub.config.js`.
+
+```bash
+dochub init my-project   # Creates ./my-project
+```
+
+### `dochub serve [directory]`
+
+Starts a development server with WebSocket live reload. Changes to any `.md` file instantly refresh the browser.
+
+```bash
+dochub serve              # Serve current directory
+dochub serve my-project   # Serve a specific project
+dochub serve -p 4000      # Custom port
+```
+
+### `dochub build [directory]`
+
+Generates a static HTML site with clean URLs. Each page becomes a directory with `index.html` — deployable to any static host (Netlify, Vercel, GitHub Pages, S3, etc.).
+
+```bash
+dochub build              # Build to ./dist
+dochub build -o docs      # Build to ./docs
+```
+
+## Configuration
+
+Edit `dochub.config.js` in your project root:
+
+```js
+module.exports = {
+  title: 'My API Docs',
+  description: 'Everything you need to build with our API',
+};
+```
+
+The title appears in the browser tab, page header, and search metadata.
+
+## Writing documentation
+
+DocHub uses standard Markdown. All files go in `markdown/` and URLs are derived from the file path:
+
+| File | URL |
+|---|---|
+| `markdown/README.md` | `/` |
+| `markdown/guide.md` | `/guide` |
+| `markdown/api/README.md` | `/api` |
+| `markdown/api/authentication.md` | `/api/authentication` |
+
+### Supported syntax
+
+- Headers (h1–h6), bold, italic, strikethrough, inline code
+- Fenced code blocks with syntax highlighting
+- Ordered and unordered lists (nested too)
+- Links, images, blockquotes, horizontal rules
+- Tables with header alignment
+
+## Deployment
+
+The `build` command outputs a static `dist/` folder:
+
+```
+dist/
+├── index.html
+├── guide/
+│   └── index.html
+├── api/
+│   └── index.html
+├── folder/
+│   └── index.html
+└── 404.html
+```
+
+Deploy the entire `dist/` folder to any static file host:
+
+<details>
+<summary><b>Netlify</b></summary>
+
+```bash
+dochub build
+# Drag dist/ onto Netlify Drop, or
+npx netlify-cli deploy --dir=dist --prod
+```
+</details>
+
+<details>
+<summary><b>Vercel</b></summary>
+
+```bash
+dochub build
+npx vercel dist --prod
+```
+</details>
+
+<details>
+<summary><b>GitHub Pages</b></summary>
+
+```bash
+dochub build
+# Push dist/ contents to gh-pages branch, or
+# use actions/upload-pages-artifact
+```
+</details>
+
+<details>
+<summary><b>Any static server</b></summary>
+
+```bash
+dochub build
+npx serve dist
+```
+</details>
+
+## Why DocHub?
+
+There are many documentation tools. Here's where DocHub fits:
+
+| | DocHub | Docusaurus | VitePress |
+|---|---|---|---|
+| Setup time | seconds | minutes | minutes |
+| Language | Markdown | MDX + React | Markdown + Vue |
+| Build output | ~20KB pages | ~200KB+ JS bundle | ~100KB+ JS bundle |
+| Dependencies | 5 packages | 200+ packages | 100+ packages |
+| Config | 5-line JS file | Full Docusaurus config | Full VitePress config |
+
+DocHub is for teams that want to write Markdown and ship docs without learning a framework or managing hundreds of dependencies.
+
+## License
+
+MIT

package/index.js

@@ -1,32 +1,86 @@
 #!/usr/bin/env node
-
-const yargs = require('yargs');
-const initProject = require('./src/init');
-const serveDocs = require('./src/serve');
-
-yargs
-  .command({
-    command: 'init <directory>',
-    describe: 'Initialize a new documentation project',
-    builder: (yargs) => {
-      yargs.positional('directory', {
-        describe: 'Directory name for the documentation project',
-        type: 'string',
-      });
-    },
-    handler: initProject,
-  })
-  .command({
-    command: 'serve <directory>',
-    describe: 'Serve the documentation site',
-    builder: (yargs) => {
-      yargs.positional('directory', {
-        describe: 'Directory name where documentation files are located',
-        type: 'string',
-      });
-    },
-    handler: serveDocs,
-  })
-  .demandCommand()
-  .help()
-  .argv;
+
+const yargs = require('yargs');
+const initProject = require('./src/init');
+const serveDocs = require('./src/serve');
+const buildSite = require('./src/build');
+
+const color = process.stdout.isTTY ? {
+  bold: (s) => `\x1b[1m${s}\x1b[22m`,
+  dim: (s) => `\x1b[2m${s}\x1b[22m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[39m`,
+  green: (s) => `\x1b[32m${s}\x1b[39m`,
+  red: (s) => `\x1b[31m${s}\x1b[39m`,
+  reset: (s) => `\x1b[0m${s}`,
+} : { bold: (s) => s, dim: (s) => s, cyan: (s) => s, green: (s) => s, red: (s) => s, reset: (s) => s };
+
+yargs
+  .scriptName('dochub')
+  .usage(`${color.bold('dochub')} <command> ${color.dim('[options]')}`)
+  .command({
+    command: 'init [directory]',
+    describe: `${color.green('Scaffold')} a new documentation project`,
+    builder: (yargs) => {
+      yargs.positional('directory', {
+        describe: 'Project directory name',
+        type: 'string',
+        default: 'my-docs'
+      });
+    },
+    handler: initProject,
+  })
+  .command({
+    command: 'serve [directory]',
+    describe: `${color.cyan('Start')} dev server with live reload`,
+    builder: (yargs) => {
+      yargs.positional('directory', {
+        describe: 'Project directory',
+        type: 'string',
+        default: '.'
+      }).option('port', {
+        alias: 'p',
+        describe: 'Port to listen on',
+        type: 'number',
+        default: 3000
+      });
+    },
+    handler: serveDocs,
+  })
+  .command({
+    command: 'build [directory]',
+    describe: `${color.green('Build')} static HTML site`,
+    builder: (yargs) => {
+      yargs.positional('directory', {
+        describe: 'Project directory',
+        type: 'string',
+        default: '.'
+      }).option('out', {
+        alias: 'o',
+        describe: 'Output directory',
+        type: 'string',
+        default: 'dist'
+      });
+    },
+    handler: buildSite,
+  })
+  .demandCommand(1, '')
+  .example('dochub init my-docs', '  Scaffold a new project')
+  .example('dochub serve', '         Start dev server in current dir')
+  .example('dochub serve --port 8080', '  Start on a custom port')
+  .example('dochub build', '         Build static site to ./dist')
+  .example('dochub build -o docs', '  Build to a custom output dir')
+  .epilogue([
+    '',
+    `  ${color.dim('Learn more:')} ${color.cyan('https://github.com/tyler-Github/dochub')}`,
+    ''
+  ].join('\n'))
+  .strict()
+  .wrap(90)
+  .fail((msg, err) => {
+    if (err) throw err;
+    if (msg) console.error(`\n  ${color.red('!')} ${msg}\n`);
+    yargs.showHelp();
+    process.exit(1);
+  })
+  .help()
+  .argv;

package/package.json

@@ -1,20 +1,37 @@
 {
   "name": "dochub",
-  "version": "1.0.4",
+  "version": "2.0.0",
+  "description": "A modern documentation generator with live-reload dev server and static site builder",
   "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
   "bin": {
     "dochub": "./index.js"
   },
+  "scripts": {
+    "test": "node index.js --help"
+  },
   "author": "Tyler Reece",
-  "license": "ISC",
-  "description": "DocHub is a documentation generation CLI tool.",
+  "license": "MIT",
   "dependencies": {
-    "child_process": "^1.0.2",
-    "fs": "^0.0.1-security",
-    "path": "^0.12.7",
+    "chokidar": "^5.0.0",
+    "highlight.js": "^11.11.1",
+    "marked": "^18.0.5",
+    "ws": "^8.21.0",
     "yargs": "^17.7.2"
-  }
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "templates/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "documentation",
+    "docs",
+    "markdown",
+    "static-site-generator",
+    "documentation-generator",
+    "live-reload"
+  ]
 }

package/src/build.js

@@ -0,0 +1,90 @@
+const fs = require('fs');
+const path = require('path');
+const { renderMarkdown } = require('./markdown');
+const { generatePageHtml } = require('./template');
+const { loadConfig, walkMarkdownFiles, getSearchData, generateSidebarHtml, extractTitle } = require('./utils');
+
+function buildSite(argv) {
+  const directory = path.resolve(argv.directory || '.');
+  const outDir = path.resolve(argv.out || 'dist');
+  const markdownDir = path.join(directory, 'markdown');
+
+  if (!fs.existsSync(markdownDir)) {
+    console.error(`No 'markdown' directory found in ${directory}.`);
+    console.error('Run `dochub init` first to scaffold a project.');
+    process.exit(1);
+  }
+
+  const config = loadConfig(directory);
+
+  if (fs.existsSync(outDir)) {
+    fs.rmSync(outDir, { recursive: true, force: true });
+  }
+
+  const files = walkMarkdownFiles(markdownDir, markdownDir);
+  const allSearchData = getSearchData(directory);
+
+  let count = 0;
+  for (const file of files) {
+    const content = fs.readFileSync(file.path, 'utf8');
+    const contentHtml = renderMarkdown(content);
+    const searchData = allSearchData.map(s => ({
+      path: s.path,
+      title: s.title,
+      excerpt: s.excerpt,
+    }));
+
+    const sidebarHtml = generateSidebarHtml(directory, file.url);
+
+    const html = generatePageHtml({
+      config,
+      sidebarHtml,
+      contentHtml,
+      searchData,
+      currentPath: file.url,
+      isDev: false,
+    });
+
+    let outputPath;
+    if (file.url === '/' || file.url === '') {
+      outputPath = path.join(outDir, 'index.html');
+    } else {
+      outputPath = path.join(outDir, file.url.slice(1), 'index.html');
+    }
+
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, html, 'utf8');
+    count++;
+  }
+
+  const homeMarkdown = path.join(markdownDir, 'README.md');
+  if (!fs.existsSync(homeMarkdown)) {
+    const allSearchData = getSearchData(directory);
+    const sidebarHtml = generateSidebarHtml(directory, '/');
+    const html = generatePageHtml({
+      config,
+      sidebarHtml,
+      contentHtml: '<h1>Welcome</h1><p>Select a page from the sidebar.</p>',
+      searchData: allSearchData,
+      currentPath: '/',
+      isDev: false,
+    });
+    const indexPath = path.join(outDir, 'index.html');
+    fs.mkdirSync(path.dirname(indexPath), { recursive: true });
+    fs.writeFileSync(indexPath, html, 'utf8');
+    count++;
+  }
+
+  const notFoundHtml = `<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1.0"><title>404 - ${config.title}</title>
+<style>body{font-family:-apple-system,sans-serif;display:flex;align-items:center;justify-content:center;min-height:100vh;margin:0;background:#0b1120;color:#f1f5f9;text-align:center}.wrap{max-width:480px}h1{font-size:4rem;margin:0;color:#60a5fa}p{color:#94a3b8;margin:1rem 0 2rem}a{color:#60a5fa;text-decoration:none;border:1px solid #60a5fa;padding:.5rem 1.5rem;border-radius:8px}a:hover{background:#60a5fa;color:#0b1120}</style></head>
+<body><div class="wrap"><h1>404</h1><p>The page you're looking for doesn't exist.</p><a href="/">Go Home</a></div></body></html>`;
+  fs.writeFileSync(path.join(outDir, '404.html'), notFoundHtml, 'utf8');
+
+  console.log(`\n  \x1b[1mDocHub\x1b[0m build complete`);
+  console.log(`  \x1b[36m>\x1b[0m  Pages:   ${count}`);
+  console.log(`  \x1b[36m>\x1b[0m  Output:  \x1b[1m${outDir}\x1b[0m\n`);
+}
+
+module.exports = buildSite;