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})],
})

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.

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

Then you can import the markdown file as a string:

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:

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

| Methods | Description | |-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------| | 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 | Description | |-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 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.