SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场docs-plugin

docs-plugin

写作与研究

查看项目

更新于 10-16 04:02

技能介绍

用途

docs-plugin 是 udecode/plate 项目中的一项技能（Skill），用于指导 Plate 编辑器插件的文档撰写。根据资料，它“保持范围狭窄”，只负责插件页面的具体规范；而共享的文档规则（如语气、通道选择、归属边界、反冗余规则、共享文档结构）已归属 docs-creator。

主要能力与写作原则

该技能规定插件文档的核心取向：

  • 写作风格：保持类似 shadcn 的直截了当（但详尽更好）、用简单英语、便于普通英语读者阅读的风格；并遵循既有文档（如 index.mdx、installation.mdx，尤其是 plate-ui.mdx）的简洁性、语气与风格。首次在文档中提及 Plate UI 时，应加上链接。
  • Headless 取向：插件文档是 headless 的，不要假设用户直接使用 Plate UI 文件或组件。文档应聚焦于核心编辑器/插件用法、API 与 transforms，且只能基于从源码确认的实际插件能力。提到 UI 组件时，应将其作为插件功能可被渲染的示例，并尽量链接到对应的 Plate UI registry 条目或组件文档页。
  • 样式插件注意：部分“Style”插件（如行高、字体颜色）主要通过向既有元素（如段落或标题）注入 props 来实现功能，而不定义全新的独立 UI 组件；其 Kit Usage 与 Manual Usage 部分应体现对配置与 prop 注入的侧重。

结构与格式

技能规定文档的结构与格式要求：

  • 过程性说明（安装、使用步骤）使用 <Steps>；<Steps> 内的子标题使用 ###。
  • 可参考 dnd.mdx 作为结构与格式的主要示例。
  • 使用 <API name="ApiName">、<APIOptions>、<APIParameters>、<APIReturns> 来记录插件选项、API 方法与 transforms；所有记录的选项与行为必须准确且来源于代码。
  • 更新既有文档时保留现有 API 格式，不要将 <APIOptions> 改为 <APIParameters>（或反向），若其已存在且工作正常。

技能还给出插件文档的“标准章节顺序”，并说明各章节的编写方式：

  • 特性（Features）：用要点总结关键能力（基于对插件的理解得出）。
  • Kit Usage（如适用，且因是最快方式而排在前面）：将步骤置于 <Steps> 中；包括安装说明（含 <ComponentSource name="relevant-kit-name" />），并紧跟一条与该插件相关的 Kit 内 UI 组件要点列表（带链接）；随后展示如何将 Kit 加入 plugins（给出 import 与 createPlateEditor 代码示例）。
  • Manual Usage：将步骤置于 <Steps> 中；包括使用 npm install 命令安装核心插件包；展示特定插件的 import 语句，并给出将其加入 createPlateEditor 的 plugins 数组的基础代码片段（并提示 ParagraphPlugin 默认已包含，通常无需显式添加，除非要覆盖其组件）；随后说明配置插件：
    • 对于元素插件（带组件）：仅有组件时优先用 withComponent；当除组件外还有额外选项时使用 .configure()，并说明 node.component、shortcuts.toggle 等实际选项。
    • 对于样式插件（无独立组件）：聚焦 inject.nodeProps、默认值、目标元素等配置，如 inject.nodeProps.defaultNodeValue、inject.targetPlugins。
  • 添加工具栏按钮：对于可被转换或插入的元素插件，可加入 Turn Into Toolbar Button 与 Insert Toolbar Button 的代码片段；仅在适合这些上下文的元素插件（块、列表等）中才包含这些章节；使用恰当的动词（“toggle”用于 turn-into，“insert”用于 insert）。若 Kit 中包含工具栏按钮，可加入“You can add *ToolbarButton to your Toolbar to .”的内容。
  • Plugins：记录每个相关插件并附简单描述（如“Plugin for H1 heading elements”）；对具有重要配置选项的插件，可选地用 <API name="PluginName"> 与 <APIOptions> 详述源码中实际存在的可配置项；不要在用户未要求时用编造的选项扩展此节。
  • API（如适用）：记录源码中实际存在的 editor.api.pluginName.* 函数，每个函数用 ### api.<name>。
  • Transforms（如适用）：记录实际存在的 editor.tf.pluginName.* 函数，精确描述源码中观察到的行为，每个函数用 ### tf.<name>。

链接与冗余

技能强调优先链接到具体、独立的文档页（如子插件或相关概念），以避免内容重复；不要使用泛泛的“See plugin guide”，而应尽量在句子中把相关词或短语智能地链接到目标页。资料中列出应链接到的文档类别，包括 All docs、Get Started、Installation Details、Guides、Plugins、Components、Kits、API Reference 等具体路径。

适用场景

该技能适用于在 udecode/plate 项目中撰写或更新插件文档页面的场景，帮助维护插件文档在结构、风格与准确性上的一致性。

限制

该技能职责范围狭窄，只负责插件页面的具体规范；共享的文档规则（语气、通道选择、归属边界、反冗余规则、共享文档结构）由 docs-creator 负责，不在本技能范围内。它要求只记录源码中真实存在的选项与行为，不编造功能；部分章节（如 API、Transforms、插件配置详述）仅在用户要求时才展开。

关于该技能的具体安装命令、收费方式、支持的平台等信息，资料中暂未提供。