# @q42/sanity-plugin-user-guide

> A Sanity plugin to add a simple user guide to the CMS

Latest version **1.1.0** (published 2026-02-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install @q42/sanity-plugin-user-guide
pnpm add @q42/sanity-plugin-user-guide
yarn add @q42/sanity-plugin-user-guide
bun add @q42/sanity-plugin-user-guide
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2026-02-19 |
| First published | 2024-04-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 5 |
| Unpacked size | 135.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 12 |
| Author | Q42 |
| Maintainers | vanoorschot, q42jaap, roelfjan, mrtnkl, lukasvan3l, jaapmengers, tstikvoort, rubenbimmel, cptmeatball, m0rph3v5, rcjkierkels, frankr, sandervw, tea-lover-418, lenverstijnen |
| Keywords | sanity, sanity-plugin |

## Links

- npm: https://www.npmjs.com/package/@q42/sanity-plugin-user-guide
- Repository: https://github.com/Q42/sanity-plugin-user-guide
- Issues: https://github.com/Q42/sanity-plugin-user-guide/issues
- npm.io page: https://npm.io/package/@q42/sanity-plugin-user-guide

## Dependencies (5)

- [remark-gfm](https://npm.io/package/remark-gfm.md) ^4.0.0
- [@sanity/uuid](https://npm.io/package/@sanity/uuid.md) ^3.0.2
- [@sanity/icons](https://npm.io/package/@sanity/icons.md) ^2.11.8
- [react-markdown](https://npm.io/package/react-markdown.md) ^9.0.1
- [@sanity/incompatible-plugin](https://npm.io/package/@sanity/incompatible-plugin.md) ^1.0.4

## Recent versions

- 1.1.0 (latest) — 2026-02-19
- 1.0.1 — 2024-05-17
- 1.0.0 — 2024-05-17
- 0.0.4 — 2024-05-06
- 0.0.3 — 2024-05-03
- 0.0.2 — 2024-05-03
- 0.0.1 — 2024-04-29

## README

# sanity-plugin-user-guide

> This is a **Sanity Studio v3** plugin.

![image](https://github.com/Q42/sanity-plugin-user-guide/assets/24476678/ee440336-8a85-45ea-b8d9-4304e09e5648)

## Installation

```sh
npm install @q42/sanity-plugin-user-guide
```

## Usage

Define your page structure for the user guide:

```ts
const userGuideStructure = defineUserGuide([
  page().title('Home').markdown(home).icon(HomeIcon),
  divider(),
  page().title('ContactPage').markdown(contactPage).icon(CommentIcon).documentType('contactPage'),
  multiPage().title('ContentPage').icon(DocumentIcon).pages([
    page().title('Creating a content page').markdown(creatingAContentPage).documentType('contentPage'),
    page().title('Content Blocks').markdown(contentBlocks),
    page().title('Uploading media').markdown(uploadingMedia),
  ]),
]);
```

Add it as a plugin in `sanity.config.ts` (or .js):

```ts
import {defineConfig} from 'sanity'
import {userGuidePlugin} from '@q42/sanity-plugin-user-guide'

export default defineConfig({
  //...
  plugins: [userGuidePlugin({userGuideStructure})],
})
```


### Using Markdown files

If you want to import markdown files from a typescript file, you can add the following snippet to your `global.d.ts`.

```ts
declare module '*.md' {
  const content: string;
  export default content;
}
```

Then you can import the markdown file as a string:

```ts
import home from './home.md';
```

## API Reference

The plugin uses an API similar to Sanity's structure builder to define the user guide structure. Currently, the following methods are available:

### Page

A single page in the user guide. To describe the content of the page, you can use either markdown or a react component.

It is possible to link a page to document type(s) or id(s). This will add it to the user menu for those documents. Clicking the link will open the user guide in a side panel of the structure tool.

#### Example:

```ts
page().title('Home').markdown(home).icon(HomeIcon).documentType('home')
```

| Methods                       | Description                                                                                                                                                 |
|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **title(title)**              | Sets the title of the page.<br/><br/>Parameters:<br/>**title**: string                                                                                      |
| **slug(slug)**                | Sets the slug of the page. Uses the title by default.<br/><br/>Parameters:<br/>**slug**: string                                                             |
| **markdown(markdown)**        | Sets the content of the page using markdown.<br/><br/>Parameters:<br/>**markdown**: string                                                                  |
| **component(component)**      | Sets the content of the page using a React component.<br/><br/>Parameters:<br/>**component**: React.ElementType                                             |
| **icon(icon)**                | Sets an Icon for this page in the page tree.<br/><br/>Parameters:<br/>**icon**: React.ElementType                                                           |
| **documentType(documentType)**| Selects one or multiple document types that link to this page.<br/><br/>Parameters:<br/>**documentType**: string \| string[]                                |
| **documentId(documentId)**    | Selects one or multiple document IDs that link to this page.<br/><br/>Parameters:<br/>**documentId**: string \| string[]                                    |

### Multi Page

A page that contains multiple subpages. This is useful for splitting up a large topic into multiple steps.

#### Example:

```ts
multiPage().title('ContentPage').icon(DocumentIcon).pages([
  page().title('Creating a content page').markdown(creatingAContentPage).documentType(contentPage),
  page().title('Content Blocks').markdown(contentBlocks),
  page().title('Uploading media').markdown(uploadingMedia),
])
```

| Methods         | Description                                                                                                                                                          |
|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **title(title)**| Sets the title of the page.<br/><br/>Parameters:<br/>**title**: string                                                                                               |
| **slug(slug)**  | Sets the slug of the page. Uses the title by default.<br/><br/>Parameters:<br/>**slug**: string                                                                      |
| **pages(pages)**| Set the pages to be displayed within this multi page. You can use the page method above to generate these pages.<br/><br/>Parameters:<br/>**pages**: PageBuilder[]   |
| **icon(icon)**  | Sets an Icon for this page in the page tree.<br/><br/>Parameters:<br/>**icon**: React.ElementType                                                                    |

### Divider

A simple divider in the user guide tree to separate groups of pages. This has no additional methods.

#### Example:

```ts
divider()
```

## License

[MIT](LICENSE) © Q42

## Develop & test

This plugin uses [@sanity/plugin-kit](https://github.com/sanity-io/plugin-kit)
with default configuration for build & watch scripts.

See [Testing a plugin in Sanity Studio](https://github.com/sanity-io/plugin-kit#testing-a-plugin-in-sanity-studio)
on how to run this plugin with hotreload in the studio.

---
_Source: https://npm.io/package/@q42/sanity-plugin-user-guide · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._