@q42/sanity-plugin-user-guide v1.0.1

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

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

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.