npm package: @growthbeaker/vscode-help-docs
Description: A reusable VS Code webview panel that renders a folder of markdown files with a navigation sidebar
Latest version: 0.1.3

# 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 @growthbeaker/vscode-help-docs
```

## Quick Start

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

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

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