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

npm install @growthbeaker/vscode-help-docs

Quick Start

import { createHelpPanel } from "@growthbeaker/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:

{
  "contributes": {
    "commands": [{
      "command": "myExtension.openHelp",
      "title": "Open Help"
    }]
  }
}

Writing Content

Markdown files

Each .md file uses YAML frontmatter for metadata:

---
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:

{
  "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

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

const help = createHelpPanel(config);

help.navigateTo("features/overview.md");   // Navigate by relative file path
help.navigateToTitle("FAQ");               // Navigate by frontmatter title (case-insensitive)
help.refresh();                            // Rebuild nav tree
help.dispose();                            // Close the panel

navigateToTitle searches the nav tree for a page whose frontmatter title matches (case-insensitive). If no match is found, it shows an error in the webview and stays on the current page.

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:

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:

[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