@q42/sanity-plugin-user-guide
TypeScript icon, indicating that this package has built-in type declarations

1.0.1 • Public • Published

sanity-plugin-user-guide

This is a Sanity Studio v3 plugin.

image

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.

Readme

Keywords

Package Sidebar

Install

npm i @q42/sanity-plugin-user-guide

Weekly Downloads

13

Version

1.0.1

License

MIT

Unpacked Size

138 kB

Total Files

31

Last publish

Collaborators

  • bkiers
  • djohalo2
  • noushavandijk
  • bennycoomans-q42
  • vanoorschot
  • q42jaap
  • roelfjan
  • mrtnkl
  • lukasvan3l
  • jaapmengers
  • tstikvoort
  • jirinrin
  • rubenbimmel
  • cptmeatball
  • m0rph3v5
  • rcjkierkels
  • frankr