# burgee/help

> Every export of burgee/help, with its signature and doc comment: renderHelp, plus 3 types.

Source: https://burgee.interlace.tools/docs/api/help

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

`burgee/help` — the help renderer, by itself. See `index.ts` for why it is not in the barrel.

```ts
import { renderHelp } from 'burgee/help';
```

## Functions

### renderHelp

Render help for one node — a runnable command, a group, or both — as text.
Deterministic for a given node and width; a snapshot suite pins it. With `color`
off — the default — a theme changes nothing; with it on, only ANSI is added.

```ts
function renderHelp(manifest: Manifest, node: CommandNode, opts?: HelpOptions): string;
```

| Parameter | Type |
| :-- | :-- |
| `manifest` | `Manifest` |
| `node` | `CommandNode` |
| `opts` (optional) | `HelpOptions` |

**Returns** `string`

## Interfaces

### HelpOptions

```ts
interface HelpOptions {
    /** Columns available; 100 when unknown, never `process.stdout` directly (H3). */
    width?: number;
    /** Show type hints such as `[string]`; off by default (H6). */
    verbose?: boolean;
    /** Apply colour (R7). Off by default: the renderer is pure, so the TTY and NO_COLOR decision stays with the caller. */
    color?: boolean;
    /**
     * Replaces the default styling token by token; read only when `color` is on. See
     * `HelpTheme` for the lines it leaves plain: the `Usage:` command name and `$ example`.
     */
    theme?: HelpTheme;
    /**
     * The commands to list, in place of the node's visible children: each by its path from the
     * node, with what it takes (`config get <key>`), under the heading of the child it is reached
     * through. The engine passes every command that runs when they fit (`listed` in `usage.ts`).
     */
    commands?: readonly CommandNode[];
}
```

## Types

### HelpTheme

Per-token styling for help (R7). A user who has `roundel` passes its tokens; a user
who does not gets the defaults. Help reads `heading`, `command`, `flag` and `value`;
the others are accepted so one theme object serves the whole output stack.

What the theme does not touch: the command name after `Usage:` and every `$ example`
line are rendered plain, whatever the theme says. Styling wraps a finished cell, so a
name is measured and padded plain and never coloured in the manifest (yargs #1699).

```ts
type HelpTheme = Partial<Record<HelpToken, (s: string) => string>>;
```

### HelpToken

The token names of `roundel`'s R3, typed structurally: help never imports the tokens (U13).

```ts
type HelpToken = 'error' | 'warn' | 'ok' | 'hint' | 'muted' | 'command' | 'flag' | 'value' | 'heading';
```