跳到主要内容

🧭 插件文档写作规范（通用）

适用范围：docs/plugins/<PluginName>/wiki 下所有插件文档内容页。统一风格、提升可读性与维护效率。

目录结构​

  • 推荐分区：入门 / 配置 / 运维 / 集成 / 架构
  • 每个插件的分区目录：getting-started、configuration、operations、integrations、architecture
  • 目录页 README 作为入口；分区内容由目录自动生成

Emoji​

  • 仅文档一级标题（H1）允许使用 emoji
  • 二级及以下标题不使用 emoji

标题与排序​

  • 删除内容标题中的数字序号（如“01.”“02.”）
  • 如需排序，使用文件名数字前缀（例如 01-xxx.md），不在正文展示序号

提示块（admonitions）​

  • 类型与标题统一：
    • 信息：info → “信息”
    • 提示：tip → “提示”
    • 警告：warning/danger → “警告”
  • 摆放位置：紧跟分节标题，顶格；不要插在列表或代码块中间
  • 典型用法：
    • 信息：中立说明、概览、路径规范
    • 提示：最佳实践、操作建议
    • 警告：风险、前置条件、易错点

文案风格​

  • 中文优先、简洁直接；必要技术词保持原文（config.yml 字段名、命令、占位符）
  • 列表短句；示例代码紧随说明段落

链接与代码​

  • 链接使用相对路径
  • 代码块使用合适语言标签（yaml、bash、text、json 等）

版本与变更​

  • 大改前先在测试环境验证；涉及价格函数、刷新策略等高风险项需明确“警告”提示
  • 新文档按规范完成后再加入对应目录

示例​

## 分节标题
:::info 信息
用于中立说明或概览的提示块。
:::
:::tip 提示
用于最佳实践与建议操作的提示块。
:::
:::warning 警告
用于风险与前置条件的提示块。
:::

提示词（Prompt）​

你是插件维基文档编辑助手，请严格遵循以下规范：
1) 仅在文档一级标题使用 emoji，二级及以下标题禁止使用 emoji；
2) 删除内容标题中的数字序号（如“01.”），保留文件名数字前缀用于排序；
3) 提示块类型与标题统一：info→“信息”，tip→“提示”，warning/danger→“警告”；
4) 提示块位置紧跟分节标题且顶格摆放，不插入列表或代码块中间；
5) 目录结构保持：入门/配置/运维/集成/架构；分区目录自动生成，README 为入口；
6) 文案简洁、中文优先；示例代码紧随说明；链接使用相对路径；
7) 编辑完成后自检上述规则是否全部满足，必要时自动修正。