Docs Plugin

Standard Section Order

Plugin documentation should generally follow this order:

1. <ComponentPreview name="relevant-demo" /> (Optional): If a relevant visual demo exists in the project.

2. <PackageInfo>:

   • Features: Bullet points summarizing key capabilities (derived from understanding the plugin).

3. ## Kit Usage (If applicable and comes first since it's the fastest approach):

   • Enclose steps within <Steps>.

   • ### Installation:

     • The fastest way to add the ... plugin is with the ...Kit, which includes pre-configured ...Plugin along with ... and their Plate UI components.
     • Include <ComponentSource name="relevant-kit-name" />.
     • Immediately follow with a bullet list of UI components from the kit relevant to the documented plugin, with links:
       • Example:
         • SpecificElement: Renders the main element.
         • SpecificToolbarButton: Provides a toolbar button.

   • ### Add Kit:

     • Show how to add the kit to plugins:

       import { createPlateEditor } from 'platejs/react';
       import { RelevantKit } from '@/components/editor/plugins/relevant-kit-name';
       
       const editor = createPlateEditor({
         plugins: [
           // ...otherPlugins,
           ...RelevantKit,
         ],
       });
       

4. ## Manual Usage:

   • Enclose steps within <Steps>.

   • ### Installation:

     • The npm install @platejs/package-name command for the core plugin package.

   • ### Add Plugin (or Add Plugins if documenting multiple plugins in this step):

     • Show the import statement for the specific plugin(s) being documented.

     • Provide a basic code snippet demonstrating how to add the plugin to the plugins array within createPlateEditor.

       import { SpecificPlugin } from '@platejs/specific-package/react';
       import { createPlateEditor } from 'platejs/react';
       
       const editor = createPlateEditor({
         plugins: [
           // ...otherPlugins,
           SpecificPlugin, // Or SpecificPlugin.configure({}) if options are common at this stage
         ],
       });
       

     • Note: ParagraphPlugin from platejs/react is included by default and usually doesn't need to be explicitly added unless overriding its component (e.g., ParagraphPlugin.withComponent(CustomParagraph)).

   • ### Configure Plugin (or Configure Plugins if documenting multiple plugins in this step):

     • Detail essential configuration options for the specific plugin using code examples, based on what is available in the plugin's source.

     For Element Plugins (with components):

     • Prioritize withComponent when only assigning a component without other options:

       import { SpecificPlugin } from '@platejs/specific-package/react';
       import { createPlateEditor } from 'platejs/react';
       import { SpecificElement } from '@/components/ui/specific-node';
       
       const editor = createPlateEditor({
         plugins: [
           // ...otherPlugins,
           SpecificPlugin.withComponent(SpecificElement),
         ],
       });
       

       • withComponent: Assigns SpecificElement to render the plugin's elements.

     • Use .configure() when there are additional options beyond the component:

       import { SpecificPlugin } from '@platejs/specific-package/react';
       import { createPlateEditor } from 'platejs/react';
       import { SpecificElement } from '@/components/ui/specific-node';
       
       const editor = createPlateEditor({
         plugins: [
           // ...otherPlugins,
           SpecificPlugin.configure({
             node: { component: SpecificElement },
             shortcuts: { toggle: 'mod+alt+s' },
             // ...other actual options from the plugin source
           }),
         ],
       });
       

       • node.component: Assigns SpecificElement to render the plugin's elements.
       • shortcuts.toggle: Defines a keyboard shortcut to toggle the feature.
       • (Explain other demonstrated options based on their actual function in the plugin)

     For Style Plugins (without distinct components):

   • ### Add to Toolbar Buttons (For Element Plugins):

     • For element plugins that can be turned into or inserted, add sections showing how to integrate with specialized toolbar buttons:

     Turn Into Toolbar Button:

     ### Turn Into Toolbar Button
     
     You can add these items to the [Turn Into Toolbar Button](/docs/toolbar#turn-into-toolbar-button) to convert blocks into [elements]:
     
     ```tsx
     {
       icon: <SpecificIcon />,
       keywords: ['keyword1', 'keyword2', 'symbol'],
       label: 'Element Name',
       value: KEYS.elementKey,
     }
     ```
     

     Insert Toolbar Button:

     ### Insert Toolbar Button
     
     You can add these items to the [Insert Toolbar Button](/docs/toolbar#insert-toolbar-button) to insert [element] elements:
     
     ```tsx
     {
       icon: <SpecificIcon />,
       label: 'Element Name',
       value: KEYS.elementKey,
     }
     ```
     

     • Only include these sections for element plugins that make sense in these contexts (blocks, lists, etc.)
     • Use appropriate action verbs: "toggle" for turn-into, "insert" for insert

   • ### Add Toolbar Button (If the kit includes a toolbar button):

     • Include "You can add *ToolbarButton to your Toolbar to <action>."
     • Check registry-kits.ts to see if a *-toolbar-button is part of the kit's dependencies.

5. ## Plugins:

   • ### PluginName: Document each relevant plugin with a simple description (e.g., "Plugin for H1 heading elements").
   • For plugins with significant configuration options, optionally use <API name="PluginName"> and <APIOptions> to detail actual, existing configurable options as found in the source code.
   • Do not extend this section with invented options if the user didn't ask for it.

6. ## API (If applicable):

   • Document actual, existing editor.api.pluginName.* functions as found in the source code.
   • Use ### api.<name> for each function.
   • Do not extend this section if the user didn't ask for it.

7. ## Transforms (If applicable):

   • Document actual, existing editor.tf.pluginName.* functions, describing their precise behavior as observed in the source code.
   • Use ### tf.<name> for each function.
   • Do not extend this section if the user didn't ask for it.

Linking and Redundancy

• Prioritize linking to individual, specific documentation pages (e.g., for a sub-plugin or a related concept) to avoid content duplication. Instead of a generic "See plugin guide", try to smartly link a relevant word or phrase within a sentence to the target page.

• All docs:

  Get Started:

  • /docs: Introduction to Plate
  • /docs/installation: Getting Started / Installation Overview

  Installation Details:

  • /docs/installation/plate-ui: Plate UI Installation
  • /docs/installation/next: Next.js Setup
  • /docs/installation/rsc: React Server Components (RSC)
  • /docs/installation/node: Node.js Usage
  • /docs/installation/mcp: MCP Server

  Guides:

  • /docs/plugin: Plugin System Overview
  • /docs/plugin-methods: Plugin Methods
  • /docs/plugin-shortcuts: Plugin Shortcuts
  • /docs/plugin-context: Plugin Context
  • /docs/plugin-components: Plugin Components Guide
  • /docs/editor: Editor Configuration
  • /docs/editor-methods: Editor Methods
  • /docs/controlled: Controlled Editor Value
  • /docs/static: Static Rendering
  • /docs/html: HTML Serialization (Guide)
  • /docs/markdown: Markdown Serialization (Guide)
  • /docs/form: Form Integration
  • /docs/typescript: TypeScript Usage
  • /docs/debugging: Debugging
  • /docs/troubleshooting: Troubleshooting

  Plugins (Overview & Individual - see apps/www/src/config/docs-plugins.ts for full list):

  • /docs/plugins: Plugins Overview (links to specific plugin docs)

  Components:

  • /docs/components: UI Components Overview (Toolbar, Nodes, etc.)
    • Links to individual component pages like /docs/components/blockquote-node, etc.

  Kits:

  • Plugin Kits: All plugin kits
    • Links to individual kit pages like /docs/kits/basic-blocks-kit, etc.

  API Reference:

  • /docs/api: API Overview
  • Core: /docs/api/core/plate-editor, /docs/api/core/plate-plugin, /docs/api/core/plate-components, /docs/api/core/plate-store, /docs/api/core/plate-controller
  • Slate Extensions: /docs/api/slate (and its sub-pages like /docs/api/slate/editor-api
  • Utilities: /docs/api/utils, /docs/api/cn, /docs/api/floating, /docs/api/react-utils, /docs/api/resizable

By following this guide, plugin documentation will be consistent, informative, and align with the project's overall documentation strategy.

Focus on configuration options like inject.nodeProps, default values, and target elements:

import { SpecificPlugin } from '@platejs/specific-package/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    SpecificPlugin.configure({
      inject: {
        nodeProps: {
          defaultNodeValue: 'defaultValue',
          // ...other nodeProps options
        },
        targetPlugins: ['p', 'h1', 'h2'],
      },
    }),
  ],
});

• inject.nodeProps.defaultNodeValue: Sets the default value for the styling property.
• inject.targetPlugins: Specifies which element types receive the styling.