@q42/sanity-plugin-user-guide

sanity-plugin-user-guide

This is a Sanity Studio v3 plugin.

Installation

npm install sanity-plugin-user-guide

Usage

Define your page structure for the user guide:

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

import {defineConfig} from 'sanity'
import {userGuidePlugin} from 'sanity-plugin-user-guide'

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

API Reference

The plugin uses a StructureBuilder-like API to define the user guide structure in a similar way to how you would define the CMS 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.

Example:

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

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

Multi Page

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

Example:

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
title(title) Sets the title of the page. Parameters: title: string
slug(slug) Sets the slug of the page. Uses the title by default. Parameters: 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. Parameters: pages: PageBuilder[]
icon(icon) Sets an Icon for this page in the page tree. Parameters: icon: React.ElementType

Divider

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

Example:

divider()

License

MIT © Q42

Develop & test

This plugin uses @sanity/plugin-kit with default configuration for build & watch scripts.

See Testing a plugin in Sanity Studio on how to run this plugin with hotreload in the studio.