Docs Plugin

Plugin Documentation Guide

General Principles

1. Writing Style:

   • Maintain a "shadcn-like straight to the point (but exhaustive is good) simple english easy to read for average english speakers" writing style.
   • Adhere to the conciseness, tone, and style of existing key documentation files like index.mdx, installation.mdx, and especially plate-ui.mdx. When mentioning Plate UI for the first time in a document, ensure it is linked.

2. Headless Approach:

   • Plugin documentation is headless. Do not assume users are using Plate UI files or components directly.
   • Focus on documenting core editor/plugin usage, APIs, and transforms based only on actual plugin capabilities confirmed from the source code.
   • When mentioning UI components, refer to them as examples of how a plugin's functionality can be rendered. Link to their Plate UI registry entries or component documentation pages if available (e.g., /docs/components/component-name).
   • Note for Style Plugins: Some plugins, particularly "Style" plugins (e.g., for line height, font color), primarily function by injecting props into existing elements (like paragraphs or headings) rather than defining entirely new, distinct UI components. Their documentation in "Kit Usage" and "Manual Usage" sections will reflect this emphasis on configuration and prop injection. See documentation in /docs/(guides)/plugin.mdx if needed.

3. Structure and Formatting:

   • Use <Steps> for procedural instructions (e.g., installation, usage steps).
   • Use ### for sub-headings within <Steps>.
   • Refer to dnd.mdx as a primary example for structure and formatting.
   • Employ <API name="ApiName">, <APIOptions>, <APIParameters>, and <APIReturns> for documenting plugin options, API methods, and transforms. Ensure all documented options and behaviors are accurate and sourced from the code.
   • Important: When updating existing documentation, preserve existing API formatting. Do not change <APIOptions> to <APIParameters> or vice versa if they already exist and are working correctly.

Standard Section Order

Plugin documentation should generally follow this order:

1. (Optional): If a relevant visual demo exists in the project.

2. :

   • 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):

     • 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.

   • ### 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 ."
     • 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.