living-documentation 1.0.0

package/README.md

@@ -0,0 +1,178 @@
+# Living Documentation
+
+A CLI tool that serves a local Markdown documentation viewer in your browser.
+
+No cloud, no database, no build step — just point it at a folder of `.md` files.
+
+![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)
+![License](https://img.shields.io/badge/License-MIT-lightgrey)
+
+---
+
+## Features
+
+- **Sidebar** grouped by category, sorted by date (newest first)
+- **Full-text search** — instant filter + server-side content search
+- **Dark mode** — follows system preference, manually toggleable
+- **Export to PDF** — print-friendly layout via `window.print()`
+- **Deep links** — share a direct URL to any document (`?doc=…`)
+- **Admin panel** — configure title, theme, filename pattern in the browser
+- **Zero frontend build** — Tailwind and highlight.js loaded from CDN
+
+---
+
+## Quick start
+
+```bash
+npx living-documentation ./path/to/docs
+```
+
+Then open [http://localhost:4321](http://localhost:4321).
+
+---
+
+## Installation
+
+### npx (no install)
+
+```bash
+npx living-documentation ./docs
+```
+
+### Global install
+
+```bash
+npm install -g living-documentation
+living-documentation ./docs
+```
+
+### Local development
+
+```bash
+git clone <repo>
+cd living-documentation
+npm install
+npm run dev -- ./docs        # runs via ts-node, no build needed
+```
+
+---
+
+## Usage
+
+```
+living-documentation [folder] [options]
+
+Arguments:
+  folder                Path to the documentation folder (default: ".")
+
+Options:
+  -p, --port <number>   Port to listen on (default: 4321)
+  -o, --open            Open browser automatically
+  -V, --version         Print version
+  -h, --help            Show help
+```
+
+**Examples:**
+
+```bash
+living-documentation ./docs
+living-documentation ./docs --port 4000 --open  # override port
+living-documentation .                          # current folder
+```
+
+---
+
+## Filename convention
+
+Documents are parsed using this default pattern:
+
+```
+YYYY_MM_DD_[Category]_title_words.md
+```
+
+| Part | Example | Parsed as |
+|------|---------|-----------|
+| `2024_01_15` | `2024_01_15` | Date → Jan 15, 2024 |
+| `[DevOps]` | `[DevOps]` | Category → DevOps |
+| `deploy_pipeline` | `deploy_pipeline` | Title → Deploy Pipeline |
+
+**Full example:**
+```
+2024_01_15_[DevOps]_deploy_pipeline.md
+2024_03_20_[Frontend]_react_hooks_guide.md
+2023_11_03_[Backend]_api_versioning_strategy.md
+```
+
+Files that don't match the pattern are still shown — they appear under **Uncategorized** with the filename as the title.
+
+---
+
+## Config file
+
+A `.living-doc.json` file is created automatically in your docs folder on first run:
+
+```json
+{
+  "docsFolder": "/absolute/path/to/docs",
+  "filenamePattern": "YYYY_MM_DD_[Category]_title",
+  "title": "Living Documentation",
+  "theme": "system",
+  "port": 4321
+}
+```
+
+You can edit it manually or use the **Admin panel** at [http://localhost:4321/admin](http://localhost:4321/admin).
+
+---
+
+## Project structure
+
+```
+living-documentation/
+├── bin/
+│   └── cli.ts              CLI entry point
+├── src/
+│   ├── server.ts            Express app
+│   ├── routes/
+│   │   ├── documents.ts     Documents API
+│   │   └── config.ts        Config API
+│   ├── lib/
+│   │   ├── parser.ts        Filename parser
+│   │   └── config.ts        Config management
+│   └── frontend/
+│       ├── index.html       Main viewer
+│       └── admin.html       Admin panel
+├── scripts/
+│   └── copy-assets.js       Build helper (copies HTML to dist/)
+├── package.json
+└── tsconfig.json
+```
+
+---
+
+## API reference
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/documents` | List all documents with metadata |
+| `GET` | `/api/documents/:id` | Get document content + rendered HTML |
+| `GET` | `/api/documents/search?q=` | Full-text search |
+| `GET` | `/api/config` | Read config |
+| `PUT` | `/api/config` | Update config (`title`, `theme`, `filenamePattern`) |
+
+---
+
+## Build
+
+```bash
+npm run build    # compiles TypeScript → dist/ and copies HTML assets
+```
+
+The compiled package is self-contained inside `dist/`. Only `dist/` is included in the npm publish.
+
+---
+
+## License
+
+MIT

package/dist/bin/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/bin/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../bin/cli.ts"],"names":[],"mappings":""}

package/dist/bin/cli.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const server_1 = require("../src/server");
+const program = new commander_1.Command();
+program
+    .name('living-documentation')
+    .description('Serve a local Markdown documentation viewer')
+    .version('1.0.0')
+    .argument('[folder]', 'Path to documentation folder', '.')
+    .option('-p, --port <number>', 'Port to listen on', '4321')
+    .option('-o, --open', 'Open browser automatically')
+    .action(async (folder, options) => {
+    const docsPath = path_1.default.resolve(process.cwd(), folder);
+    if (!fs_1.default.existsSync(docsPath)) {
+        console.error(`\nError: Folder not found: ${docsPath}\n`);
+        process.exit(1);
+    }
+    const stat = fs_1.default.statSync(docsPath);
+    if (!stat.isDirectory()) {
+        console.error(`\nError: Not a directory: ${docsPath}\n`);
+        process.exit(1);
+    }
+    const port = parseInt(options.port, 10);
+    if (isNaN(port) || port < 1 || port > 65535) {
+        console.error('\nError: Invalid port number\n');
+        process.exit(1);
+    }
+    await (0, server_1.startServer)({ docsPath, port, openBrowser: options.open ?? false });
+});
+program.parse();
+//# sourceMappingURL=cli.js.map

package/dist/bin/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../bin/cli.ts"],"names":[],"mappings":";;;;;;AAEA,yCAAoC;AACpC,gDAAwB;AACxB,4CAAoB;AACpB,0CAA4C;AAE5C,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,sBAAsB,CAAC;KAC5B,WAAW,CAAC,6CAA6C,CAAC;KAC1D,OAAO,CAAC,OAAO,CAAC;KAChB,QAAQ,CAAC,UAAU,EAAE,8BAA8B,EAAE,GAAG,CAAC;KACzD,MAAM,CAAC,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,CAAC;KAC1D,MAAM,CAAC,YAAY,EAAE,4BAA4B,CAAC;KAClD,MAAM,CAAC,KAAK,EAAE,MAAc,EAAE,OAAwC,EAAE,EAAE;IACzE,MAAM,QAAQ,GAAG,cAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC,CAAC;IAErD,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,KAAK,CAAC,8BAA8B,QAAQ,IAAI,CAAC,CAAC;QAC1D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,IAAI,GAAG,YAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACnC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;QACxB,OAAO,CAAC,KAAK,CAAC,6BAA6B,QAAQ,IAAI,CAAC,CAAC;QACzD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACxC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;QAC5C,OAAO,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;QAChD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,IAAA,oBAAW,EAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,IAAI,IAAI,KAAK,EAAE,CAAC,CAAC;AAC5E,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/dist/src/frontend/admin.html

@@ -0,0 +1,268 @@
+<!DOCTYPE html>
+<html lang="en" class="h-full">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Admin — Living Documentation</title>
+
+  <script src="https://cdn.tailwindcss.com"></script>
+
+  <script>
+    tailwind.config = { darkMode: 'class', theme: { extend: {} } };
+  </script>
+
+  <style>
+    .field-label { @apply block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1; }
+    .field-input {
+      @apply w-full px-3 py-2 rounded-lg border border-gray-200 dark:border-gray-700
+             bg-white dark:bg-gray-800 text-gray-900 dark:text-gray-100
+             placeholder:text-gray-400 focus:outline-none focus:ring-2 focus:ring-blue-500 text-sm;
+    }
+    .field-hint { @apply mt-1 text-xs text-gray-400 dark:text-gray-500; }
+  </style>
+</head>
+
+<body class="h-full bg-gray-50 dark:bg-gray-950 text-gray-900 dark:text-gray-100">
+
+  <!-- ── Header ── -->
+  <header class="flex items-center justify-between px-6 h-14 border-b border-gray-200 dark:border-gray-800
+                 bg-white dark:bg-gray-900 shadow-sm">
+    <div class="flex items-center gap-3">
+      <a href="/" class="text-blue-600 dark:text-blue-400 hover:underline text-sm">
+        &#8592; Back to docs
+      </a>
+      <span class="text-gray-300 dark:text-gray-700">|</span>
+      <h1 class="text-sm font-semibold">Admin Panel</h1>
+    </div>
+
+    <button id="dark-toggle" title="Toggle dark mode"
+            class="p-2 rounded-lg text-gray-500 dark:text-gray-400 hover:bg-gray-100 dark:hover:bg-gray-800 transition-colors">
+      <span id="dark-icon" class="text-lg leading-none">☾</span>
+    </button>
+  </header>
+
+  <!-- ── Page ── -->
+  <main class="max-w-2xl mx-auto px-6 py-10">
+
+    <!-- Title -->
+    <div class="mb-8">
+      <h2 class="text-xl font-bold text-gray-900 dark:text-gray-50">Configuration</h2>
+      <p class="mt-1 text-sm text-gray-500 dark:text-gray-400">
+        Settings are saved to <code class="text-xs bg-gray-100 dark:bg-gray-800 px-1.5 py-0.5 rounded">.living-doc.json</code>
+        in your docs folder.
+      </p>
+    </div>
+
+    <!-- ── Form ── -->
+    <form id="config-form" class="space-y-6" novalidate>
+
+      <!-- Read-only info card -->
+      <div class="rounded-xl border border-gray-200 dark:border-gray-800 bg-white dark:bg-gray-900 p-5">
+        <h3 class="text-sm font-semibold text-gray-700 dark:text-gray-300 mb-4">Server Info</h3>
+        <dl class="grid grid-cols-2 gap-x-6 gap-y-3 text-sm">
+          <div>
+            <dt class="text-xs text-gray-400 uppercase tracking-wide mb-0.5">Docs Folder</dt>
+            <dd id="info-folder" class="font-mono text-xs text-gray-700 dark:text-gray-300 break-all">—</dd>
+          </div>
+          <div>
+            <dt class="text-xs text-gray-400 uppercase tracking-wide mb-0.5">Port</dt>
+            <dd id="info-port" class="font-mono text-xs text-gray-700 dark:text-gray-300">—</dd>
+          </div>
+        </dl>
+      </div>
+
+      <!-- Editable settings -->
+      <div class="rounded-xl border border-gray-200 dark:border-gray-800 bg-white dark:bg-gray-900 p-5 space-y-5">
+        <h3 class="text-sm font-semibold text-gray-700 dark:text-gray-300">Appearance & Metadata</h3>
+
+        <!-- Site Title -->
+        <div>
+          <label class="field-label" for="field-title">Site Title</label>
+          <input id="field-title" name="title" type="text" class="field-input"
+                 placeholder="Living Documentation" />
+          <p class="field-hint">Displayed in the browser tab and sidebar header.</p>
+        </div>
+
+        <!-- Theme -->
+        <div>
+          <label class="field-label" for="field-theme">Default Theme</label>
+          <select id="field-theme" name="theme" class="field-input">
+            <option value="system">System (follow OS preference)</option>
+            <option value="light">Light</option>
+            <option value="dark">Dark</option>
+          </select>
+          <p class="field-hint">Users can always override this with the toggle button.</p>
+        </div>
+
+        <!-- Filename Pattern -->
+        <div>
+          <label class="field-label" for="field-pattern">Filename Pattern</label>
+          <input id="field-pattern" name="filenamePattern" type="text" class="field-input"
+                 placeholder="YYYY_MM_DD_[Category]_title" />
+          <p class="field-hint">
+            Documents matching this pattern are parsed for date, category, and title.
+            <span class="font-mono bg-gray-100 dark:bg-gray-800 px-1 rounded">YYYY_MM_DD_[Category]_title.md</span>
+          </p>
+        </div>
+      </div>
+
+      <!-- Pattern preview -->
+      <div id="pattern-preview"
+           class="rounded-xl border border-blue-100 dark:border-blue-900 bg-blue-50 dark:bg-blue-950/30 p-5">
+        <h3 class="text-sm font-semibold text-blue-700 dark:text-blue-400 mb-3">Pattern Preview</h3>
+        <p class="text-xs text-gray-500 dark:text-gray-400 mb-3">How your pattern parses example filenames:</p>
+        <div id="preview-rows" class="space-y-2 text-sm"></div>
+      </div>
+
+      <!-- Submit -->
+      <div class="flex items-center justify-between">
+        <div id="save-msg" class="text-sm"></div>
+        <button type="submit"
+                class="px-5 py-2 rounded-lg bg-blue-600 hover:bg-blue-700 text-white font-semibold text-sm
+                       transition-colors focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 dark:focus:ring-offset-gray-900">
+          Save changes
+        </button>
+      </div>
+    </form>
+
+  </main>
+
+<script>
+// ── Boot ───────────────────────────────────────────────────
+document.addEventListener('DOMContentLoaded', async () => {
+  applyDarkMode(loadDarkPref());
+  setupDarkToggle();
+  await loadConfig();
+  setupPatternPreview();
+  document.getElementById('config-form').addEventListener('submit', saveConfig);
+});
+
+// ── Dark mode ──────────────────────────────────────────────
+function loadDarkPref() {
+  const saved = localStorage.getItem('ld-dark');
+  if (saved !== null) return saved === 'true';
+  return window.matchMedia('(prefers-color-scheme: dark)').matches;
+}
+function applyDarkMode(dark) {
+  document.documentElement.classList.toggle('dark', dark);
+  document.getElementById('dark-icon').textContent = dark ? '☀' : '☾';
+}
+function setupDarkToggle() {
+  document.getElementById('dark-toggle').addEventListener('click', () => {
+    const isDark = document.documentElement.classList.toggle('dark');
+    localStorage.setItem('ld-dark', isDark);
+    document.getElementById('dark-icon').textContent = isDark ? '☀' : '☾';
+  });
+}
+
+// ── Config ─────────────────────────────────────────────────
+async function loadConfig() {
+  try {
+    const cfg = await fetch('/api/config').then(r => r.json());
+    document.getElementById('info-folder').textContent = cfg.docsFolder || '—';
+    document.getElementById('info-port').textContent   = cfg.port || '—';
+    document.getElementById('field-title').value       = cfg.title || '';
+    document.getElementById('field-theme').value       = cfg.theme || 'system';
+    document.getElementById('field-pattern').value     = cfg.filenamePattern || '';
+    updatePreview(cfg.filenamePattern);
+  } catch {
+    showMsg('Failed to load config.', 'error');
+  }
+}
+
+async function saveConfig(e) {
+  e.preventDefault();
+  const payload = {
+    title:           document.getElementById('field-title').value.trim(),
+    theme:           document.getElementById('field-theme').value,
+    filenamePattern: document.getElementById('field-pattern').value.trim(),
+  };
+
+  try {
+    const res = await fetch('/api/config', {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    });
+    if (!res.ok) throw new Error(await res.text());
+    showMsg('Saved!', 'ok');
+  } catch (err) {
+    showMsg('Save failed: ' + err.message, 'error');
+  }
+}
+
+function showMsg(text, type) {
+  const el = document.getElementById('save-msg');
+  el.textContent = text;
+  el.className = 'text-sm ' + (type === 'ok'
+    ? 'text-green-600 dark:text-green-400'
+    : 'text-red-600 dark:text-red-400');
+  if (type === 'ok') setTimeout(() => { el.textContent = ''; }, 3000);
+}
+
+// ── Pattern preview ────────────────────────────────────────
+const EXAMPLES = [
+  '2024_01_15_[DevOps]_deploy_pipeline.md',
+  '2023_11_03_[Frontend]_react_hooks_guide.md',
+  '2025_06_20_meeting_notes.md',
+  'readme.md',
+];
+
+// Parse like server does
+const FULL_PAT    = /^(\d{4}_\d{2}_\d{2})_\[([^\]]+)\]_(.+)\.md$/i;
+const DATE_ONLY   = /^(\d{4}_\d{2}_\d{2})_(.+)\.md$/i;
+
+function parsePreview(filename) {
+  const full = filename.match(FULL_PAT);
+  if (full) {
+    const [, d, cat, t] = full;
+    return { date: d.replace(/_/g,'-'), category: cat, title: titleCase(t), match: true };
+  }
+  const d = filename.match(DATE_ONLY);
+  if (d) {
+    return { date: d[1].replace(/_/g,'-'), category: 'Uncategorized', title: titleCase(d[2]), match: true };
+  }
+  return { date: null, category: 'Uncategorized', title: filename.replace('.md',''), match: false };
+}
+
+function titleCase(s) {
+  return s.split('_').map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join(' ');
+}
+
+function updatePreview() {
+  const rows = document.getElementById('preview-rows');
+  rows.innerHTML = EXAMPLES.map(f => {
+    const p = parsePreview(f);
+    return `
+      <div class="rounded-lg border border-gray-200 dark:border-gray-700 bg-white dark:bg-gray-900 p-3">
+        <p class="font-mono text-xs text-gray-500 dark:text-gray-400 mb-2 break-all">${esc(f)}</p>
+        <div class="grid grid-cols-3 gap-2 text-xs">
+          <div>
+            <span class="text-gray-400 block mb-0.5">Date</span>
+            <span class="${p.date ? 'text-green-600 dark:text-green-400' : 'text-gray-400'}">${p.date || 'none'}</span>
+          </div>
+          <div>
+            <span class="text-gray-400 block mb-0.5">Category</span>
+            <span class="text-blue-600 dark:text-blue-400">${esc(p.category)}</span>
+          </div>
+          <div>
+            <span class="text-gray-400 block mb-0.5">Title</span>
+            <span class="text-gray-700 dark:text-gray-300 truncate block">${esc(p.title)}</span>
+          </div>
+        </div>
+      </div>`;
+  }).join('');
+}
+
+function setupPatternPreview() {
+  document.getElementById('field-pattern').addEventListener('input', updatePreview);
+}
+
+function esc(s) {
+  return String(s)
+    .replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;')
+    .replace(/"/g,'&quot;').replace(/'/g,'&#39;');
+}
+</script>
+</body>
+</html>