Frontmatter 元数据指南

本文档帮助你快速为 Dify 开发者文档定义核心元数据。正确填写这些字段是实现文档自动化结构和排序的关键。

​

快速开始

使用大模型辅助

1. 准备文档内容

   完成你的文档内容撰写。

2. 使用AI生成元数据

   将你的文档和 dimensions 系统详解 的内容交给你偏好的大模型，请求生成适合的 Frontmatter。

3. 手动优化

   根据实际情况和下面的详细说明，对生成的元数据进行必要的调整和优化。

手动定义

阅读下方的详细说明，根据你的文档内容特点，自行定义适合的元数据字段。

​

必要 Frontmatter 字段

请在每篇 Markdown 文档的开头添加以下 YAML Frontmatter：

---
# --- 系统核心元数据 (影响结构和排序) ---
dimensions:
  type:
    primary: <见下方选项>
    detail: <见下方选项>
  level: <见下方选项>
standard_title: '英文描述性标题，用于生成文件名' # e.g., 'Getting Started Dify Plugin'
language: 'zh' # 或 'en', 'ja', etc. (ISO 639-2 代码)

# --- 页面内容元数据 (可选，但推荐) ---
title: '文档的 H1 标题或页面标题'
description: '文档内容的简短 SEO 描述'
# summary: '更详细的摘要 (可选)'
# tags: ['关键词'] (可选)
---

​

dimensions 字段详解

type.primary

conceptual

概念、理论 (是什么/为什么)
重点解释概念和基础理论

implementation

开发实践、代码 (如何做)
重点提供实现步骤和代码示例

operational

运维、部署 (如何运行)
重点关注系统运行和维护

reference

API、配置参考 (精确查找)
重点提供技术规格和参考信息

type.detail

在 primary 类别下的细分：

conceptual 下的细分

• introduction: 入门介绍
• principles: 设计原则
• architecture: 架构说明

implementation 下的细分

• basic: 基础实现
• standard: 标准实现
• high: 高级实现 (可能后置)
• advanced: 深度实现 (可能后置)

operational 下的细分

• setup: 环境设置
• deployment: 部署操作
• maintenance: 维护管理

reference 下的细分

• core: 核心参考
• configuration: 配置参考
• examples: 示例参考

更多选项请参考 dimensions 系统详解 文档

level

beginner

新手入门
适合初学者的入门内容

intermediate

常规用户
适合有一定基础的用户

advanced

高级用户
适合专业用户的深入内容 (通常会被后置排序)

​

其他重要字段

standard_title · string · 必填

使用英文，清晰描述文档核心内容。系统将用它生成部分文件名 (例如 Getting Started Dify Plugin)。

language · string · 必填

ISO 639-2 双字母语言代码 (如 en, zh, ja)。

title · string

文档在页面上显示的主标题，通常是本地化语言。

description · string

简短的SEO描述，用于搜索引擎和预览。

​

完整示例

入门文档示例

---
dimensions:
  type:
    primary: conceptual
    detail: introduction
  level: beginner
standard_title: 'Getting Started Dify Plugin'
language: zh
title: '欢迎开始 Dify 插件开发'
description: '介绍Dify插件的概念、功能和开发价值，包括插件类型的简要说明，以及开发者文档的内容概览。'
---

解读示例: 第一个例子是一篇面向初学者的、关于 Dify 插件概念的入门介绍文档，语言为中文。系统会根据元数据自动将其正确放置在文档结构中。

​

文档自动化处理

本地开发

运行 tools/main_docs_bundle.py，文档将被自动根据 Frontmatter 完成以下操作：

1. 重命名文件

   系统将根据 dimensions 和 standard_title 自动生成标准化文件名。

2. 更新导航

   文档将被自动注入到 docs.json 导航配置中。

3. 添加交互组件

   自动刷新贡献和反馈按钮等交互组件。

在本地环境开发文档时，建议运行该脚本确保文档配置正确生效。

GitHub 编辑

如果你在 GitHub 上直接进行编辑，无需担心自动化步骤。我们已经配置了 GitHub Action 等自动化工具，会在以下情况自动执行 tools/main_docs_bundle.py：

• 当你提交 Pull Request 时
• 当你的更改被合并到主分支时

你可以专注于内容创作，GitHub 工作流会处理文件重命名、导航更新和交互组件生成等技术细节。

想了解更多？

如果你对 Dimensions 系统的设计理念、排序机制的完整细节或角色与治理感兴趣，请阅读完整的 Dimensions 系统详解文档。

---

编辑此页面 | 提交问题