A Sanity plugin to add a simple user guide to the CMS
npm install @q42/sanity-plugin-user-guidesh
npm install 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 'sanity-plugin-user-guide'
export default defineConfig({
//...
plugins: [userGuidePlugin({userGuideStructure})],
})
`
$3
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:
$3
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.
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[] |
$3
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.
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 |
$3
A simple divider in the user guide tree to separate groups of pages. This has no additional methods.
#### Example:
`ts
divider()
``