@growthbeaker/vscode-help-docs 0.1.0

package/README.md

@@ -0,0 +1,183 @@
+# vscode-help-docs
+
+A reusable package that turns a folder of markdown files into a navigable, themed help viewer panel inside VS Code.
+
+## Why
+
+VS Code extensions that ship user-facing docs have three unsatisfying options: open an external browser (loses context), use the built-in markdown preview (no sidebar, no branding), or build a custom webview from scratch. This package eliminates that repeated work.
+
+## Install
+
+```bash
+npm install vscode-help-docs
+```
+
+## Quick Start
+
+```typescript
+import { createHelpPanel } from "vscode-help-docs";
+
+// In your extension's activate()
+const cmd = vscode.commands.registerCommand("myExtension.openHelp", () => {
+  createHelpPanel({
+    contentRoot: path.join(context.extensionPath, "help"),
+    extensionContext: context,
+    title: "My Extension Help",
+  });
+});
+
+context.subscriptions.push(cmd);
+```
+
+Register the command in your `package.json`:
+
+```json
+{
+  "contributes": {
+    "commands": [{
+      "command": "myExtension.openHelp",
+      "title": "Open Help"
+    }]
+  }
+}
+```
+
+## Writing Content
+
+### Markdown files
+
+Each `.md` file uses YAML frontmatter for metadata:
+
+```markdown
+---
+title: Getting Started
+order: 1
+hidden: false
+---
+
+# Getting Started
+
+Your content here...
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `title` | string | Filename (title-cased) | Display name in the nav sidebar |
+| `order` | number | Alphabetical | Sort position within its folder |
+| `hidden` | boolean | `false` | If `true`, excluded from nav tree |
+
+### Folder metadata
+
+Each folder can contain an optional `_meta.json`:
+
+```json
+{
+  "title": "User Guide",
+  "order": 1,
+  "collapsed": false
+}
+```
+
+### Example content tree
+
+```
+help/
+  getting-started/
+    _meta.json            → { "title": "Getting Started", "order": 1 }
+    01-installation.md
+    02-first-project.md
+  features/
+    _meta.json            → { "title": "Features", "order": 2 }
+    overview.md
+  troubleshooting/
+    _meta.json            → { "title": "Troubleshooting", "order": 3 }
+    common-issues.md
+    faq.md
+```
+
+## Configuration
+
+```typescript
+createHelpPanel({
+  // Required
+  contentRoot: string,          // Absolute path to your docs folder
+  extensionContext: ExtensionContext,
+
+  // Optional
+  title: "Help",                // Panel tab title
+  viewColumn: ViewColumn.One,   // Which editor column
+  defaultPage: "intro.md",      // Page shown on open (default: first by sort order)
+  enableAnchors: true,          // Anchor link scrolling
+  enableMermaid: false,         // Mermaid diagram rendering (see below)
+  metaFilename: "_meta.json",   // Folder metadata filename
+  customCss: "",                // Inline CSS to inject
+  customCssPath: "",            // Path to a CSS file to inject
+});
+```
+
+## API
+
+```typescript
+const help = createHelpPanel(config);
+
+help.navigateTo("features/overview.md");  // Navigate programmatically
+help.refresh();                            // Rebuild nav tree
+help.dispose();                            // Close the panel
+```
+
+Calling `createHelpPanel` with the same `contentRoot` when a panel is already open reveals the existing panel (singleton behavior).
+
+## Mermaid Diagrams
+
+Enable Mermaid diagram rendering for fenced ` ```mermaid ` code blocks:
+
+```typescript
+createHelpPanel({
+  // ...
+  enableMermaid: true,
+});
+```
+
+Supports flowcharts, sequence diagrams, class diagrams, state diagrams, pie charts, git graphs, and more.
+
+**Note:** Enabling Mermaid adds `'unsafe-inline'` to the webview's `style-src` CSP directive (Mermaid injects inline styles into SVGs). When disabled, the strict CSP is preserved.
+
+## Theming
+
+The viewer automatically adapts to the active VS Code theme (Light, Dark, High Contrast) using CSS custom properties. Override styles with `customCss` or `customCssPath`.
+
+## Error Handling
+
+The package handles common content authoring mistakes gracefully:
+
+- **Malformed YAML frontmatter** — file still appears in nav using defaults, warning logged
+- **Invalid field types** (e.g., `order: "five"`) — invalid fields fall back to defaults, valid fields preserved
+- **Malformed `_meta.json`** — folder uses defaults, siblings unaffected
+- **Circular symlinks** — detected and skipped, rest of tree built normally
+- **Excessive nesting** (>20 levels) — truncated with warning
+- **Broken internal links** — stays on current page, shows error message, logs diagnostic
+- **Missing anchors** — navigates to page, scrolls to top, shows notification
+
+## Links
+
+Internal links navigate within the viewer, external links open in the system browser:
+
+```markdown
+[Installation](../getting-started/installation.md)        <!-- internal -->
+[With anchor](../features/overview.md#configuration)       <!-- internal + anchor -->
+[VS Code](https://code.visualstudio.com)                   <!-- external -->
+```
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `markdown-it` | Markdown rendering |
+| `gray-matter` | Frontmatter parsing |
+| `mermaid` | Diagram rendering (used when `enableMermaid: true`) |
+
+Optional: `markdown-it-anchor` for heading anchor IDs.
+
+## License
+
+MIT

package/dist/extension.d.ts

@@ -0,0 +1,4 @@
+import * as vscode from 'vscode';
+export declare function activate(context: vscode.ExtensionContext): void;
+export declare function deactivate(): void;
+//# sourceMappingURL=extension.d.ts.map

package/dist/extension.js

@@ -0,0 +1,54 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.activate = activate;
+exports.deactivate = deactivate;
+const vscode = __importStar(require("vscode"));
+const path = __importStar(require("path"));
+const help_panel_1 = require("./help-panel");
+function activate(context) {
+    const cmd = vscode.commands.registerCommand('helpDocs.open', () => {
+        (0, help_panel_1.createHelpPanel)({
+            contentRoot: path.join(context.extensionPath, 'test-help'),
+            extensionContext: context,
+            title: 'Help Docs',
+            defaultPage: 'getting-started/01-installation.md',
+            enableMermaid: true,
+        });
+    });
+    context.subscriptions.push(cmd);
+}
+function deactivate() { }
+//# sourceMappingURL=extension.js.map

package/dist/help-panel.d.ts

@@ -0,0 +1,62 @@
+import * as vscode from 'vscode';
+import { HelpViewerConfig, IHelpPanel, WebviewToExtensionMessage } from './types';
+/**
+ * Create (or reveal) a Help Viewer panel.
+ * Singleton behavior: if a panel already exists for the same contentRoot, it is revealed.
+ */
+export declare function createHelpPanel(config: HelpViewerConfig): IHelpPanel;
+/**
+ * HelpPanel class implementing the Help Viewer webview panel.
+ *
+ * Implements:
+ * - screen:help-viewer-panel
+ * - flow:broken-internal-link-handler (AC 1.5.4 / nv00001)
+ * - flow:anchor-navigation-handler (AC 1.5.5 / nv00002)
+ */
+export declare class HelpPanel implements IHelpPanel {
+    readonly panel: vscode.WebviewPanel;
+    private readonly config;
+    private readonly outputChannel;
+    private navTree;
+    private currentPage;
+    constructor(config: HelpViewerConfig);
+    private initialize;
+    /**
+     * Handle messages from the webview.
+     *
+     * Implements:
+     * - flow:broken-internal-link-handler (navigateTo with missing file)
+     * - flow:anchor-navigation-handler (navigateToAnchor with missing anchor)
+     */
+    handleWebviewMessage(message: WebviewToExtensionMessage): void;
+    /**
+     * Navigate to a documentation page.
+     *
+     * AC 1.5.4 (nv00001): If the target file does not exist:
+     * - Do not navigate away from current page
+     * - Display non-blocking error message
+     * - Log warning to output channel with target path and source document
+     * - No crash/reload
+     */
+    navigateTo(relativePath: string): void;
+    /**
+     * Handle anchor navigation.
+     *
+     * AC 1.5.5 (nv00002): If the anchor is not found:
+     * - Still navigate to target page (if specified)
+     * - Scroll to top when anchor not found
+     * - Display non-blocking notification
+     * - No crash/reload
+     */
+    private handleAnchorNavigation;
+    /** Refresh the nav tree and re-render current page */
+    refresh(): Promise<void>;
+    /** Dispose the panel */
+    dispose(): void;
+    /** Get the current page path (for testing) */
+    getCurrentPage(): string | null;
+    private postMessage;
+    private findFirstPage;
+    private getWebviewHtml;
+}
+//# sourceMappingURL=help-panel.d.ts.map

package/dist/help-panel.js

@@ -0,0 +1,272 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HelpPanel = void 0;
+exports.createHelpPanel = createHelpPanel;
+const vscode = __importStar(require("vscode"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const nav_tree_1 = require("./nav-tree");
+const markdown_renderer_1 = require("./markdown-renderer");
+/** Map of contentRoot -> active HelpPanel for singleton behavior */
+const activePanels = new Map();
+/**
+ * Create (or reveal) a Help Viewer panel.
+ * Singleton behavior: if a panel already exists for the same contentRoot, it is revealed.
+ */
+function createHelpPanel(config) {
+    const existing = activePanels.get(config.contentRoot);
+    if (existing && existing.panel) {
+        existing.panel.reveal(config.viewColumn ?? vscode.ViewColumn.One);
+        return existing;
+    }
+    const panel = new HelpPanel(config);
+    activePanels.set(config.contentRoot, panel);
+    return panel;
+}
+/**
+ * HelpPanel class implementing the Help Viewer webview panel.
+ *
+ * Implements:
+ * - screen:help-viewer-panel
+ * - flow:broken-internal-link-handler (AC 1.5.4 / nv00001)
+ * - flow:anchor-navigation-handler (AC 1.5.5 / nv00002)
+ */
+class HelpPanel {
+    constructor(config) {
+        this.navTree = [];
+        this.currentPage = null;
+        this.config = config;
+        this.outputChannel = vscode.window.createOutputChannel('Help Docs');
+        this.panel = vscode.window.createWebviewPanel('helpViewer', config.title ?? 'Help', config.viewColumn ?? vscode.ViewColumn.One, {
+            enableScripts: true,
+            localResourceRoots: [
+                vscode.Uri.file(config.contentRoot),
+                vscode.Uri.file(path.join(config.extensionContext.extensionPath, 'node_modules', 'vscode-help-docs', 'src', 'webview')),
+                vscode.Uri.file(path.join(__dirname, '..', 'src', 'webview')),
+                // Allow loading mermaid.js from node_modules
+                vscode.Uri.file(path.join(__dirname, '..', 'node_modules', 'mermaid', 'dist')),
+            ],
+        });
+        this.panel.onDidDispose(() => {
+            activePanels.delete(config.contentRoot);
+            this.outputChannel.dispose();
+        });
+        this.panel.webview.onDidReceiveMessage((message) => this.handleWebviewMessage(message));
+        this.initialize();
+    }
+    async initialize() {
+        this.navTree = await (0, nav_tree_1.buildNavTree)(this.config.contentRoot, {
+            metaFilename: this.config.metaFilename,
+        });
+        this.panel.webview.html = this.getWebviewHtml();
+        // Navigate to default page or first page
+        const defaultPage = this.config.defaultPage ?? this.findFirstPage(this.navTree);
+        if (defaultPage) {
+            this.navigateTo(defaultPage);
+        }
+    }
+    /**
+     * Handle messages from the webview.
+     *
+     * Implements:
+     * - flow:broken-internal-link-handler (navigateTo with missing file)
+     * - flow:anchor-navigation-handler (navigateToAnchor with missing anchor)
+     */
+    handleWebviewMessage(message) {
+        switch (message.type) {
+            case 'navigateTo':
+                this.navigateTo(message.path);
+                break;
+            case 'navigateToAnchor':
+                this.handleAnchorNavigation(message.path, message.anchor);
+                break;
+            case 'openExternal':
+                vscode.env.openExternal(vscode.Uri.parse(message.url));
+                break;
+            case 'ready':
+                this.postMessage({ type: 'navTree', tree: this.navTree });
+                break;
+        }
+    }
+    /**
+     * Navigate to a documentation page.
+     *
+     * AC 1.5.4 (nv00001): If the target file does not exist:
+     * - Do not navigate away from current page
+     * - Display non-blocking error message
+     * - Log warning to output channel with target path and source document
+     * - No crash/reload
+     */
+    navigateTo(relativePath) {
+        const fullPath = path.join(this.config.contentRoot, relativePath);
+        // AC 1.5.4: Check if file exists
+        if (!fs.existsSync(fullPath)) {
+            // Display error message to user via webview
+            this.postMessage({
+                type: 'error',
+                message: `Page not found: \`${relativePath}\``,
+            });
+            // Log diagnostic warning to output channel
+            this.outputChannel.appendLine(`[WARN] Broken internal link to "${relativePath}" from "${this.currentPage ?? '(none)'}"`);
+            // Do NOT update currentPage — stay on current page
+            return;
+        }
+        try {
+            const rawContent = fs.readFileSync(fullPath, 'utf-8');
+            const { frontmatter, content } = (0, markdown_renderer_1.parseFrontmatter)(fullPath, rawContent);
+            const html = (0, markdown_renderer_1.renderMarkdown)(content, this.config.enableMermaid);
+            const title = frontmatter.title ?? path.basename(relativePath, '.md');
+            this.currentPage = relativePath;
+            this.postMessage({ type: 'contentLoaded', html, title, path: relativePath });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.postMessage({
+                type: 'error',
+                message: `Error loading page: ${errorMessage}`,
+            });
+        }
+    }
+    /**
+     * Handle anchor navigation.
+     *
+     * AC 1.5.5 (nv00002): If the anchor is not found:
+     * - Still navigate to target page (if specified)
+     * - Scroll to top when anchor not found
+     * - Display non-blocking notification
+     * - No crash/reload
+     */
+    handleAnchorNavigation(pagePath, anchor) {
+        // If a page path is provided, navigate to it first
+        if (pagePath) {
+            this.navigateTo(pagePath);
+        }
+        // Send anchor scroll command to webview
+        // The webview will report back if the anchor is not found
+        this.postMessage({ type: 'scrollToAnchor', anchor });
+    }
+    /** Refresh the nav tree and re-render current page */
+    async refresh() {
+        this.navTree = await (0, nav_tree_1.buildNavTree)(this.config.contentRoot, {
+            metaFilename: this.config.metaFilename,
+        });
+        this.postMessage({ type: 'navTree', tree: this.navTree });
+        if (this.currentPage) {
+            this.navigateTo(this.currentPage);
+        }
+    }
+    /** Dispose the panel */
+    dispose() {
+        this.panel.dispose();
+    }
+    /** Get the current page path (for testing) */
+    getCurrentPage() {
+        return this.currentPage;
+    }
+    postMessage(message) {
+        this.panel.webview.postMessage(message);
+    }
+    findFirstPage(nodes) {
+        for (const node of nodes) {
+            if (node.type === 'page') {
+                return node.path;
+            }
+            if (node.children) {
+                const found = this.findFirstPage(node.children);
+                if (found)
+                    return found;
+            }
+        }
+        return null;
+    }
+    getWebviewHtml() {
+        const nonce = crypto.randomBytes(16).toString('hex');
+        const cspSource = this.panel.webview.cspSource;
+        const enableMermaid = this.config.enableMermaid ?? false;
+        const styleUri = this.panel.webview.asWebviewUri(vscode.Uri.file(path.join(__dirname, '..', 'src', 'webview', 'styles.css')));
+        const scriptUri = this.panel.webview.asWebviewUri(vscode.Uri.file(path.join(__dirname, '..', 'src', 'webview', 'main.js')));
+        // Mermaid injects inline styles into SVGs, so we need 'unsafe-inline' in style-src when enabled
+        const styleSrc = enableMermaid
+            ? `${cspSource} 'nonce-${nonce}' 'unsafe-inline'`
+            : `${cspSource} 'nonce-${nonce}'`;
+        let mermaidScript = '';
+        if (enableMermaid) {
+            try {
+                const mermaidPath = require.resolve('mermaid/dist/mermaid.min.js');
+                const mermaidUri = this.panel.webview.asWebviewUri(vscode.Uri.file(mermaidPath));
+                mermaidScript = `<script nonce="${nonce}" src="${mermaidUri}"></script>`;
+            }
+            catch {
+                // mermaid not installed — skip silently
+            }
+        }
+        let customStyles = '';
+        if (this.config.customCss) {
+            customStyles += `<style nonce="${nonce}">${this.config.customCss}</style>`;
+        }
+        if (this.config.customCssPath) {
+            const customCssUri = this.panel.webview.asWebviewUri(vscode.Uri.file(this.config.customCssPath));
+            customStyles += `<link rel="stylesheet" href="${customCssUri}">`;
+        }
+        return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta http-equiv="Content-Security-Policy"
+    content="default-src 'none'; style-src ${styleSrc}; script-src 'nonce-${nonce}'; img-src ${cspSource} https:;">
+  <link rel="stylesheet" href="${styleUri}">
+  ${customStyles}
+  <title>${this.config.title ?? 'Help'}</title>
+</head>
+<body>
+  <div class="help-viewer">
+    <nav class="nav-sidebar" id="nav-sidebar"></nav>
+    <main class="content-pane" id="content-pane">
+      <div class="error-banner" id="error-banner" style="display:none;"></div>
+      <div class="notification-toast" id="notification-toast" style="display:none;"></div>
+      <article id="content-body"></article>
+    </main>
+  </div>
+  ${mermaidScript}
+  <script nonce="${nonce}" src="${scriptUri}"></script>
+</body>
+</html>`;
+    }
+}
+exports.HelpPanel = HelpPanel;
+//# sourceMappingURL=help-panel.js.map

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createHelpPanel } from './help-panel';
+export type { HelpViewerConfig, NavNode, IHelpPanel as HelpPanel, Frontmatter, FolderMeta, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHelpPanel = void 0;
+var help_panel_1 = require("./help-panel");
+Object.defineProperty(exports, "createHelpPanel", { enumerable: true, get: function () { return help_panel_1.createHelpPanel; } });
+//# sourceMappingURL=index.js.map

package/dist/markdown-renderer.d.ts

@@ -0,0 +1,27 @@
+import { Frontmatter } from './types';
+/**
+ * Parse frontmatter from a markdown file with graceful error handling.
+ *
+ * Implements:
+ * - AC 1.8.2: Malformed YAML Frontmatter Graceful Degradation
+ * - AC 1.8.3: Frontmatter Field Type Validation
+ */
+export declare function parseFrontmatter(filePath: string, rawContent: string): {
+    frontmatter: Frontmatter;
+    content: string;
+};
+/**
+ * Validate frontmatter field types, logging warnings for invalid types.
+ *
+ * Implements AC 1.8.3: Frontmatter Field Type Validation
+ */
+export declare function validateFrontmatterFields(filePath: string, data: Record<string, unknown>): Frontmatter;
+/** Render markdown content to HTML */
+export declare function renderMarkdown(content: string, enableMermaid?: boolean): string;
+/**
+ * Convert a filename to a title-cased display name.
+ * Strips .md extension, replaces hyphens/underscores with spaces,
+ * removes leading numeric prefixes (e.g., "01-"), and title-cases each word.
+ */
+export declare function titleCaseFilename(filename: string): string;
+//# sourceMappingURL=markdown-renderer.d.ts.map