@driftime/sanity-plugin-handbook 0.2.1 → 0.3.1

package/README.md

@@ -1,10 +1,8 @@
-<br />
-
 <div align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/icon-dark.svg" />
-    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/icon.svg" />
-    <img src="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/icon.svg" alt="Handbook icon" width="48" />
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/icon-light.svg" />
+    <img src="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/icon-light.svg" alt="Handbook icon" width="48" />
   </picture>
   <h1>Handbook — A Sanity Plugin</h1>
   <p>Schema-driven documentation and editorial guides, built right into Sanity Studio.</p>
@@ -14,15 +12,15 @@
 
 ## Overview
 
-Handbook adds a dedicated tool to Sanity Studio that serves two purposes: it automatically generates browsable documentation from your document type schemas, and it provides a rich text guide authoring system for editorial teams. Field descriptions, examples, tips, and warnings are pulled directly from your schema definitions, so your documentation stays in sync with your content model.
+Handbook adds a dedicated tool to Sanity Studio that serves two purposes: it automatically generates browsable documentation from your document type schemas, and it provides a rich text guide authoring system for editorial teams. Field descriptions, examples, tips, notes, and warnings are pulled directly from your schema definitions, so your documentation stays in sync with your content model.
 
 <br />
 
 <figure>
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-fields-dark.png" />
-    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-fields.png" />
-    <img src="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-fields.png" alt="The Handbook tool displaying field documentation for a Pages document type, with field names, types, descriptions, and example values" />
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-fields-light.png" />
+    <img src="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-fields-light.png" alt="The Handbook tool displaying field documentation for a Pages document type, with field names, types, descriptions, example values, and an expanded subfields section" />
   </picture>
   <p align="center"><sub><em>Field documentation generated automatically from your schema definitions.</em></sub></p>
 </figure>
@@ -31,13 +29,15 @@ Handbook adds a dedicated tool to Sanity Studio that serves two purposes: it aut
 
 ## Installation
 
+Handbook is built for Sanity Studio 6 and React 19, and declares both as peer dependencies, so your Studio must already be on those versions. You'll need Node 22.12 or later.
+
 ```bash
 bun add -E @driftime/sanity-plugin-handbook
 ```
 
 ## Basic Setup
 
-Add the plugin to your Sanity configuration and pass in the document types you want to document. Each group appears as a labelled section in the sidebar.
+Add the plugin to your Sanity configuration and pass in the document types you want to document, grouped by the role they play in your content model. Each role appears as a labelled section in the sidebar.
 
 ```typescript
 import { defineConfig } from "sanity";
@@ -48,17 +48,21 @@ export default defineConfig({
   // ...
   plugins: [
     handbookPlugin({
-      groups: [
+      roles: [
         {
           title: "Singletons",
-          description: "Unique pages that exist as a single instance and cannot be duplicated.",
-          documents: [home, work, latest],
+          description: "Document types that exist as a single instance.",
+          documents: [home],
         },
         {
           title: "Collections",
-          description:
-            "Repeatable document types with multiple entries, each representing an individually routable page.",
-          documents: [page, caseStudy, article],
+          description: "Document types with multiple entries.",
+          documents: [page],
+        },
+        {
+          title: "Globals",
+          description: "Document types shared across the site.",
+          documents: [navigation, templates, settings],
         },
       ],
     }),
@@ -66,48 +70,50 @@ export default defineConfig({
 });
 ```
 
-This registers a Handbook tool in the Studio navigation. Opening it displays a sidebar with your document types, each showing its fields with their descriptions. See [Configuration](#configuration) for all available options.
+This registers a Handbook tool in the Studio navigation. Opening it shows a sidebar that starts with a built-in Getting Started section: a page on how to read the Handbook, and an overview of every role and its document types. Your own roles follow, one labelled section each. Selecting a document type shows its fields and their descriptions, with the `icon` from its schema. See [Configuration](#configuration) for all available options.
 
 <br />
 
 <figure>
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-document-types-dark.png" />
-    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-document-types.png" />
-    <img src="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-document-types.png" alt="The Handbook tool showing document type groups in the sidebar with Singletons and Collections listed" />
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-document-types-light.png" />
+    <img src="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-document-types-light.png" alt="The Handbook tool showing the Document Types overview, with Singletons, Collections, and Globals roles each listing their document types and descriptions" />
   </picture>
-  <p align="center"><sub><em>Document types organised into groups, browsable from the sidebar.</em></sub></p>
+  <p align="center"><sub><em>Document types organised by role, browsable from the sidebar.</em></sub></p>
 </figure>
 
 <br />
 
 ## Handbook Metadata
 
-The plugin augments Sanity's `FieldDefinitionBase` and `DocumentDefinition` interfaces, adding a `handbook` property that TypeScript recognises automatically. Fields fall back to their standard `title` and `description` properties when no `handbook` metadata is provided.
+The plugin augments Sanity's `FieldDefinitionBase` and `DocumentDefinition` interfaces, adding a `handbook` property that TypeScript recognises automatically.
 
 ```typescript
 import { defineField, defineType } from "sanity";
 
 export const pageType = defineType({
   name: "page",
-  title: "Page",
   type: "document",
+  title: "Pages",
+  description: "General-purpose pages.",
   handbook: {
     title: "Page",
-    description: "A standalone page with a unique URL.",
+    description:
+      "Standalone pages for anything that does not warrant a document type of its own. Each is reached at its own address and assembled from blocks rather than following a fixed layout.",
   },
   fields: [
     defineField({
       name: "title",
-      title: "Title",
       type: "string",
-      description: "The primary heading displayed on this page.",
+      description: "Appears in navigation, browser tabs, and search results.",
       handbook: {
+        description:
+          "The name this page goes by wherever it is referred to rather than read — navigation menus, browser tabs, and search results. Every page needs one, and it stands behind the slug whenever that is left blank.",
         example: "About Acme Inc.",
-        tip: "Keep titles concise — under 60 characters for best results.",
-        info: "The title is also used to generate the page's URL slug.",
-        caution:
-          "This field is required. Publishing without a title will cause the page to be excluded from navigation and search indexing.",
+        tip: "Keep it short enough to sit comfortably in a navigation menu, and put any fuller opening line in the heading instead.",
+        info: "The slug is generated from the title once, so renaming a page later leaves its address unchanged.",
+        caution: "Required. Publishing is blocked until it is filled in.",
       },
     }),
   ],
@@ -129,17 +135,17 @@ If no `handbook` property is provided, the tool falls back to the field's `title
 
 ### Subfield Browsing
 
-Fields with nested structure display a collapsible section that editors can expand to explore subfields. Custom types extending built-in types like `image` or `file` show only the fields you add — inherited fields are excluded automatically. Circular type references are detected and labelled rather than rendering infinitely.
+Fields with nested structure display a collapsible section that editors can expand to explore subfields. Custom types extending built-in types like `image` or `file` show only the fields you add. Inherited fields are excluded automatically. Circular type references are detected and labelled rather than rendering infinitely.
 
 ## Guide Content
 
-Handbook includes a guide authoring system powered by Portable Text. The plugin automatically registers a `handbook.handbook` singleton and a `handbook.guide` document type — no additional schema setup is required.
+Handbook includes a guide authoring system powered by Portable Text. The plugin automatically registers a `handbook.handbook` singleton and a `handbook.guide` document type. No additional schema setup is required.
 
-The singleton defines the groups and ordering of your guides. Each group contains references to guide documents, which are authored using a rich text editor with built-in support for:
+The singleton defines the groups and ordering of your guides. Each group contains references to guide documents, which carry a title, an optional description shown beneath the heading, and a rich text body with built-in support for:
 
 - Paragraph, heading, and blockquote styles
-- Bold, italic, strikethrough, and inline code formatting
 - Bullet and numbered lists
+- Bold, italic, strikethrough, and inline code formatting
 - Inline links
 - Image blocks with caption and alternative text
 - Video blocks with caption
@@ -153,9 +159,9 @@ The Handbook tool displays guides in the sidebar alongside your document types.
 
 <figure>
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-structure-guide-dark.png" />
-    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-structure-guide.png" />
-    <img src="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-structure-guide.png" alt="A guide displayed in the Handbook tool with headings, paragraphs, a callout, a bullet list, and a code block" />
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-guide-dark.png" />
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-guide-light.png" />
+    <img src="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-guide-light.png" alt="A guide displayed in the Handbook tool with headings, paragraphs, a blockquote, a bullet list, a callout, and a captioned image" />
   </picture>
   <p align="center"><sub><em>Editorial guides authored with Portable Text and rendered directly in the tool.</em></sub></p>
 </figure>
@@ -166,32 +172,34 @@ The Handbook tool displays guides in the sidebar alongside your document types.
 
 Register custom Portable Text blocks for use in guide content by providing a schema definition and a React component. Custom blocks appear as insertion options in the guide content editor and are rendered using the provided component in the Handbook viewer.
 
-```typescript
+```tsx
 import { defineConfig, defineField, defineType } from "sanity";
+import type { PortableTextObject } from "sanity";
 import { handbookPlugin } from "@driftime/sanity-plugin-handbook";
 // ...
 
 const exampleSchema = defineType({
   name: "handbook.example",
-  title: "Example",
   type: "object",
+  title: "Example",
   fields: [
     defineField({
       name: "label",
-      title: "Label",
       type: "string",
+      description: "Text displayed inside the block.",
     }),
   ],
 });
 
 function ExampleBlock({ value }: { value: PortableTextObject & { label?: string } }) {
-  return <div>{value.label}</div>;
+  return <p>{value.label}</p>;
 }
 
 export default defineConfig({
   // ...
   plugins: [
     handbookPlugin({
+      // ...
       blocks: [
         {
           schema: exampleSchema,
@@ -205,67 +213,81 @@ export default defineConfig({
 
 ## Editor Permissions
 
-Restrict who can create and edit handbook documents by providing a list of email addresses.
+Restrict who can create and edit Handbook documents by providing a list of email addresses.
 
 ```typescript
 handbookPlugin({
-  editors: ["editor@acme.com", "admin@acme.com"],
+  // ...
+  editors: ["admin@acme.com", "editor@acme.com"],
 });
 ```
 
-When an editors list is provided, only users whose email appears in the list can create or manage handbook documents. Users not in the list are excluded entirely. If no editors list is provided, all users have full access.
+When an editors list is provided, only users whose email appears in the list can create or manage Handbook documents. Users not in the list are excluded entirely. If no editors list is provided, all users have full access.
 
-The `useIsHandbookEditor` hook is exported for use in your own components if you need to conditionally render UI based on editor permissions.
+Independently of that list, the Handbook singleton is locked for everyone: it never appears in the create-new menu, and its delete, duplicate, and unpublish actions are removed. Anyone the list permits can still create guides.
+
+The `useIsHandbookEditor` hook is exported for use in your own components if you need to conditionally render UI based on editor permissions. It reads the `editors` you gave the plugin, and takes a list as an optional argument to override that.
 
 ```typescript
 import { useIsHandbookEditor } from "@driftime/sanity-plugin-handbook";
 
-const isEditor = useIsHandbookEditor(["editor@acme.com"]);
+const isEditor = useIsHandbookEditor();
 ```
 
 ## Structure Integration
 
-To add handbook documents to the Structure tool sidebar, use the `handbookStructure` helper. This adds a Handbook singleton editor and a Handbook Guides list. The structure helper respects the same editor permissions configured via the plugin.
+The Handbook tool displays guides, but you author them in the Structure tool. Nothing appears there until you add it. Use the `handbookStructure` helper to add a Handbook singleton editor and a Handbook Guides list, both restricted to the same editors you gave the plugin.
+
+```typescript
+import { handbookStructure } from "@driftime/sanity-plugin-handbook";
+import type { StructureResolver } from "sanity/structure";
+
+export const structure: StructureResolver = (structureBuilder, context) => {
+  const { list, documentTypeListItems, divider } = structureBuilder;
+
+  const handbookItems = handbookStructure(structureBuilder, context);
+
+  return list()
+    .title("Content")
+    .items([
+      ...documentTypeListItems().filter(
+        (item) => !["handbook.handbook", "handbook.guide"].includes(item.getId() ?? ""),
+      ),
+      ...(handbookItems.length > 0 ? [divider(), ...handbookItems] : []),
+    ]);
+};
+```
+
+The helper needs two things from your structure. It reads the current user from the resolver's second argument, so accept both parameters even if the rest of your structure only needs the builder. It also returns an empty array for users outside the editors list, so only add the divider when there are items. Otherwise those users see a divider with nothing under it.
+
+The helper reads the `editors` you gave the plugin, so you don't declare them twice. Pass a list as the optional third argument to override that, which you need if your Studio runs several workspaces with different editors.
+
+The filter is only needed where a structure draws on `documentTypeListItems()`, which lists every registered type and so includes the two the plugin adds. A structure built from your own document definitions won't include them, so you can drop the filter.
+
+The Handbook singleton is where you define guide groups and their ordering. Each group contains references to individual guide documents that editors can reorder as needed.
 
 <br />
 
 <figure>
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-structure-dark.png" />
-    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-structure.png" />
-    <img src="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-structure.png" alt="The Handbook singleton editor in the Structure tool, showing reorderable groups each containing guide references" />
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-groups-dark.png" />
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-groups-light.png" />
+    <img src="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-groups-light.png" alt="The Handbook singleton editor in the Structure tool, showing reorderable groups each containing guide references" />
   </picture>
   <p align="center"><sub><em>The Handbook singleton where groups and their ordering are managed.</em></sub></p>
 </figure>
 
 <br />
 
-```typescript
-import { handbookStructure } from "@driftime/sanity-plugin-handbook";
-
-export const structure = (structureBuilder, context) => {
-  return structureBuilder
-    .list()
-    .title("Content")
-    .items([
-      ...structureBuilder
-        .documentTypeListItems()
-        .filter((item) => !["handbook.handbook", "handbook.guide"].includes(item.getId() ?? "")),
-      structureBuilder.divider(),
-      ...handbookStructure(structureBuilder, context),
-    ]);
-};
-```
-
-Individual guides are authored as `handbook.guide` documents, which can be created and edited directly from the Structure tool.
+Individual guides are authored as `handbook.guide` documents, which can be created and edited directly from the Structure tool using the built-in Portable Text editor.
 
 <br />
 
 <figure>
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-structure-guides-dark.png" />
-    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-structure-guides.png" />
-    <img src="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-structure-guides.png" alt="The Handbook Guides list in the Structure tool, showing individual guide documents available for editing" />
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-editor-dark.png" />
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-editor-light.png" />
+    <img src="https://raw.githubusercontent.com/driftime/sanity-plugin-handbook/HEAD/.github/assets/handbook-editor-light.png" alt="The Handbook Guides list in the Structure tool with a guide open beside it, showing its title, description, and Portable Text content editor" />
   </picture>
   <p align="center"><sub><em>Handbook Guides listed in the Structure tool for authoring and editing.</em></sub></p>
 </figure>
@@ -274,16 +296,47 @@ Individual guides are authored as `handbook.guide` documents, which can be creat
 
 ## Configuration
 
-All configuration is optional. The plugin works out of the box with sensible defaults.
+Only `roles` is required, since it tells the plugin which document types to cover. Everything else falls back to a sensible default.
+
+| Option                     | Type                              | Default                                                                                 | Purpose                                                                          |
+| -------------------------- | --------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `title`                    | `string`                          | `"Handbook"`                                                                            | Title shown in the Studio tool navigation.                                       |
+| `sidebarTitle`             | `string`                          | `"Handbook"`                                                                            | Heading displayed at the top of the sidebar.                                     |
+| `roles`                    | `SanityHandbookDocumentRole[]`    | — (required)                                                                            | Document roles, each shown as a labelled section in the sidebar.                 |
+| `blocks`                   | `SanityHandbookBlockDefinition[]` | `[]`                                                                                    | Custom Portable Text block definitions for guide content.                        |
+| `editors`                  | `string[]`                        | `undefined`                                                                             | Email addresses permitted to edit Handbook documents. Unrestricted when omitted. |
+| `undocumentedFieldMessage` | `string`                          | `"This field has not been documented yet. Contact your development team for guidance."` | Fallback message shown when a field has no description.                          |
+
+## Exported Types
+
+These types are exported for typing your own configuration and for querying Handbook content outside the Studio.
+
+Configuration you supply:
+
+| Type                            | Purpose                                                                     |
+| ------------------------------- | --------------------------------------------------------------------------- |
+| `SanityHandbookMetadata`        | The `handbook` property added to field and document definitions.            |
+| `SanityHandbookDocumentRole`    | A named role, holding the document types that fill it.                      |
+| `SanityHandbookBlockDefinition` | A custom Portable Text block, pairing a schema definition with a component. |
+| `SanityHandbookConfig`          | The full plugin configuration accepted by `handbookPlugin`.                 |
+
+Content the dataset stores:
+
+| Type                           | Purpose                                                                   |
+| ------------------------------ | ------------------------------------------------------------------------- |
+| `SanityHandbook`               | The Handbook singleton document, defining the groups and their ordering.  |
+| `SanityHandbookGuideGroup`     | A group within the Handbook singleton, holding an ordered list of guides. |
+| `SanityHandbookGuide`          | A guide document, with its title, description, and Portable Text content. |
+| `SanityHandbookCallout`        | A callout block, with its variant and Portable Text body.                 |
+| `SanityHandbookCode`           | A code block, with its source and language.                               |
+| `SanityHandbookHorizontalRule` | A horizontal rule block.                                                  |
+| `SanityHandbookImage`          | An image block, with its asset, caption, and alternative text.            |
+| `SanityHandbookVideo`          | A video block, with its asset and caption.                                |
+| `SanityHandbookLink`           | A link annotation, with the web address it points to.                     |
+
+## Acknowledgements
 
-| Option                     | Type                        | Default                                                                                 | Purpose                                                                          |
-| -------------------------- | --------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| `title`                    | `string`                    | `"Handbook"`                                                                            | Title shown in the Studio tool navigation.                                       |
-| `sidebarTitle`             | `string`                    | `"Handbook"`                                                                            | Heading displayed at the top of the sidebar.                                     |
-| `groups`                   | `HandbookStructureGroup[]`  | `[]`                                                                                    | Document type groups defining the sidebar hierarchy.                             |
-| `blocks`                   | `HandbookBlockDefinition[]` | `[]`                                                                                    | Custom Portable Text block definitions for guide content.                        |
-| `editors`                  | `string[]`                  | `undefined`                                                                             | Email addresses permitted to edit handbook documents. Unrestricted when omitted. |
-| `undocumentedFieldMessage` | `string`                    | `"This field has not been documented yet. Contact your development team for guidance."` | Fallback message shown when a field has no description.                          |
+The icons in `src/icons` are derived from [Lucide](https://lucide.dev) and redrawn as standalone components, so the plugin ships its own icons without depending on the Lucide package. Icons for controls the Studio already draws, such as disclosure arrows, come from `@sanity/icons` so they match their surroundings. Lucide is distributed under the [ISC License](https://github.com/lucide-icons/lucide/blob/main/LICENSE).
 
 <br />
 <br />