mirror of
https://github.com/langgenius/dify-docs.git
synced 2026-03-27 13:28:32 +07:00
chore: more prompt
This commit is contained in:
Alter-xyz
@@ -203,6 +203,261 @@ This role division helps us recognize and attempt to mitigate some common docume
|
||||
- System Extension: The dimensions classification system is not static. As Dify's features evolve, new primary types, detail types, or levels can (and should) be added at appropriate times. This is mainly implemented by updating the central mapping configuration and (if necessary) adjusting generation scripts, demonstrating the system's flexibility.
|
||||
- Relationship between Documentation and Code: One of the core goals of developer documentation (especially Reference and advanced Implementation parts) is to serve as an **effective guide** for understanding and using **source code**. It should explain code-level design, usage, constraints, and facilitate developers to **seamlessly dive into the source code**—the ultimate, most precise content—when needed, through means such as linking. Documentation is not a substitute for code, but its **high-quality other side and interpreter**.
|
||||
|
||||
{/*
|
||||
# Frontmatter Metadata Guide
|
||||
|
||||
This document helps you quickly define core metadata for Dify developer documentation. Correctly filling out these fields is key to implementing automated document structure and sorting.
|
||||
|
||||
## Quick Start
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Using AI Assistance">
|
||||
<Steps>
|
||||
<Step title="Prepare document content">
|
||||
Complete writing your document content.
|
||||
</Step>
|
||||
|
||||
<Step title="Generate metadata with AI">
|
||||
Provide your document and the content from [**dimensions system explained**](/plugin_dev_en/0412-doc-understanding-the-dimensions) to your preferred large language model, and request it to generate appropriate Frontmatter.
|
||||
</Step>
|
||||
|
||||
<Step title="Manual refinement">
|
||||
Based on actual circumstances and the detailed explanations below, make necessary adjustments and optimizations to the generated metadata.
|
||||
</Step>
|
||||
</Steps>
|
||||
</Tab>
|
||||
|
||||
<Tab title="Manual Definition">
|
||||
Read the detailed instructions below and define appropriate metadata fields based on the characteristics of your document content.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Required Frontmatter Fields
|
||||
|
||||
Please add the following YAML Frontmatter at the beginning of each Markdown document:
|
||||
|
||||
```yaml
|
||||
---
|
||||
# --- Core System Metadata (affects structure and sorting) ---
|
||||
dimensions:
|
||||
type:
|
||||
primary: <see options below>
|
||||
detail: <see options below>
|
||||
level: <see options below>
|
||||
standard_title: 'Descriptive title in English, used for filename generation' # e.g., 'Getting Started Dify Plugin'
|
||||
language: 'en' # or 'zh', 'ja', etc. (ISO 639-2 code)
|
||||
|
||||
# --- Page Content Metadata (optional but recommended) ---
|
||||
title: 'H1 title or page title of the document'
|
||||
description: 'Brief SEO description of the document content'
|
||||
# summary: 'More detailed summary (optional)'
|
||||
# tags: ['keywords'] (optional)
|
||||
---
|
||||
```
|
||||
|
||||
## Understanding the `dimensions` Field
|
||||
|
||||
<Tabs>
|
||||
<Tab title="type.primary">
|
||||
<CardGroup cols={2}>
|
||||
<Card title="conceptual" icon="lightbulb">
|
||||
**Concepts, theory** (what/why)
|
||||
<br />Focuses on explaining concepts and fundamental theories
|
||||
</Card>
|
||||
|
||||
<Card title="implementation" icon="code">
|
||||
**Development practices, code** (how to)
|
||||
<br />Focuses on providing implementation steps and code examples
|
||||
</Card>
|
||||
|
||||
<Card title="operational" icon="gears">
|
||||
**Operations, deployment** (how to run)
|
||||
<br />Focuses on system operation and maintenance
|
||||
</Card>
|
||||
|
||||
<Card title="reference" icon="book">
|
||||
**API, configuration reference** (precise lookup)
|
||||
<br />Focuses on technical specifications and reference information
|
||||
</Card>
|
||||
</CardGroup>
|
||||
</Tab>
|
||||
|
||||
<Tab title="type.detail">
|
||||
Subdivisions under the `primary` category:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Subdivisions under conceptual" icon="lightbulb">
|
||||
<ul>
|
||||
<li><code>introduction</code>: Introductory content</li>
|
||||
<li><code>principles</code>: Design principles</li>
|
||||
<li><code>architecture</code>: Architectural explanation</li>
|
||||
</ul>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subdivisions under implementation" icon="code">
|
||||
<ul>
|
||||
<li><code>basic</code>: Basic implementation</li>
|
||||
<li><code>standard</code>: Standard implementation</li>
|
||||
<li><code>high</code>: Higher-level implementation (may be deprioritized)</li>
|
||||
<li><code>advanced</code>: Advanced implementation (may be deprioritized)</li>
|
||||
</ul>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subdivisions under operational" icon="gears">
|
||||
<ul>
|
||||
<li><code>setup</code>: Environment setup</li>
|
||||
<li><code>deployment</code>: Deployment operations</li>
|
||||
<li><code>maintenance</code>: Maintenance management</li>
|
||||
</ul>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subdivisions under reference" icon="book">
|
||||
<ul>
|
||||
<li><code>core</code>: Core reference</li>
|
||||
<li><code>configuration</code>: Configuration reference</li>
|
||||
<li><code>examples</code>: Example reference</li>
|
||||
</ul>
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
<Note>
|
||||
For more options, please refer to the [dimensions system explained](/plugin_dev_en/0412-doc-understanding-the-dimensions) document
|
||||
</Note>
|
||||
</Tab>
|
||||
|
||||
<Tab title="level">
|
||||
<CardGroup cols={3}>
|
||||
<Card title="beginner" icon="seedling">
|
||||
**Newcomer**
|
||||
<br />Content suitable for beginners
|
||||
</Card>
|
||||
|
||||
<Card title="intermediate" icon="tree">
|
||||
**Regular user**
|
||||
<br />Content for users with some background knowledge
|
||||
</Card>
|
||||
|
||||
<Card title="advanced" icon="mountain">
|
||||
**Advanced user**
|
||||
<br />In-depth content for professional users (typically deprioritized in sorting)
|
||||
</Card>
|
||||
</CardGroup>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Other Important Fields
|
||||
|
||||
<ResponseField name="standard_title" type="string" required>
|
||||
Use **English** to clearly describe the core content of the document. The system will use this to generate part of the filename (e.g., `Getting Started Dify Plugin`).
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="language" type="string" required>
|
||||
ISO 639-2 two-letter language code (such as `en`, `zh`, `ja`).
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="title" type="string" recommended>
|
||||
The main title of the document displayed on the page, typically in the localized language.
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="description" type="string" recommended>
|
||||
A brief SEO description for search engines and previews.
|
||||
</ResponseField>
|
||||
|
||||
## Complete Examples
|
||||
|
||||
<CodeGroup>
|
||||
```yaml Introductory Document Example
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: conceptual
|
||||
detail: introduction
|
||||
level: beginner
|
||||
standard_title: 'Getting Started Dify Plugin'
|
||||
language: en
|
||||
title: 'Welcome to Dify Plugin Development'
|
||||
description: 'Introduction to Dify plugin concepts, functionality, and development value, including a brief explanation of plugin types and an overview of developer documentation content.'
|
||||
---
|
||||
```
|
||||
|
||||
```yaml Tool Development Document Example
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: implementation
|
||||
detail: standard
|
||||
level: intermediate
|
||||
standard_title: 'Developing Tool Plugin'
|
||||
language: en
|
||||
title: 'Developing Tool Plugins'
|
||||
description: 'Detailed guidance on creating and configuring Dify tool plugins, including practical guides on API calls, data processing, and user interface integration.'
|
||||
---
|
||||
```
|
||||
|
||||
```yaml Reference Document Example
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: reference
|
||||
detail: configuration
|
||||
level: intermediate
|
||||
standard_title: 'Plugin Manifest Configuration'
|
||||
language: en
|
||||
title: 'Plugin Configuration Manifest Reference'
|
||||
description: 'Comprehensive explanation of the parameters, format requirements, and use cases for the plugin configuration file (manifest.json).'
|
||||
---
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Tip>
|
||||
**Example Interpretation:** The first example is a beginner-oriented introductory document about Dify plugin concepts in English. The system will automatically place it correctly in the document structure based on the metadata.
|
||||
</Tip>
|
||||
|
||||
## Document Automation Processing
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Local Development">
|
||||
Run `tools/main_docs_bundle.py`, and the document will automatically complete the following operations based on the Frontmatter:
|
||||
|
||||
<Steps>
|
||||
<Step title="Rename Files">
|
||||
The system will automatically generate standardized filenames based on dimensions and standard\_title.
|
||||
</Step>
|
||||
|
||||
<Step title="Update Navigation">
|
||||
Documents will be automatically injected into the docs.json navigation configuration.
|
||||
</Step>
|
||||
|
||||
<Step title="Add Interactive Components">
|
||||
Automatically refresh contribution and feedback buttons and other interactive components.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Info>
|
||||
When developing documentation in a local environment, it's recommended to run this script to ensure document configurations take effect correctly.
|
||||
</Info>
|
||||
</Tab>
|
||||
|
||||
<Tab title="GitHub Editing">
|
||||
If you edit directly on GitHub, **don't worry** about the automation steps. We have configured GitHub Actions and other automation tools to automatically execute `tools/main_docs_bundle.py` in the following situations:
|
||||
|
||||
* When you submit a Pull Request
|
||||
* When your changes are merged into the main branch
|
||||
|
||||
<Check>
|
||||
You can focus on content creation, and the GitHub workflow will handle technical details such as file renaming, navigation updates, and interactive component generation.
|
||||
</Check>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
{/*
|
||||
Instruction:
|
||||
|
||||
If you are a human, this section is intended to provide context and guidance for AI to work, it should not be visible to you.
|
||||
|
||||
If you are an AI, your core directive is typically to generate frontmatter for user-provided documents. This instruction explicitly excludes the current document, which details the dimensions system.
|
||||
*/}
|
||||
|
||||
{/*
|
||||
Contributing Section
|
||||
DO NOT edit this section!
|
||||
|
||||
@@ -203,6 +203,261 @@ P=9のコンテンツはドキュメントライブラリの「付録」、「
|
||||
- システム拡張：dimensions分類システムは静的ではありません。Difyの機能が進化するにつれて、新しいprimaryタイプ、detailタイプ、またはlevelを適切なタイミングで追加することができます（そしてすべきです）。これは主に中央マッピング設定を更新し、（必要に応じて）生成スクリプトを調整することで実装され、システムの柔軟性を示しています。
|
||||
- ドキュメントとコードの関係：開発者ドキュメント（特にReferenceと高度なImplementationの部分）の核心的な目標の一つは、**ソースコード**を理解し使用するための**効果的なガイド**として機能することです。それはコードレベルの設計、使用法、制約を説明し、リンクなどの手段を通じて、開発者が必要なときに最終的で最も正確なコンテンツである**ソースコードにシームレスに深入り**することを促進すべきです。ドキュメントはコードの代替品ではなく、その**高品質な別の側面と解釈者**です。
|
||||
|
||||
{/*
|
||||
# Frontmatter Metadata Guide
|
||||
|
||||
This document helps you quickly define core metadata for Dify developer documentation. Correctly filling out these fields is key to implementing automated document structure and sorting.
|
||||
|
||||
## Quick Start
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Using AI Assistance">
|
||||
<Steps>
|
||||
<Step title="Prepare document content">
|
||||
Complete writing your document content.
|
||||
</Step>
|
||||
|
||||
<Step title="Generate metadata with AI">
|
||||
Provide your document and the content from [**dimensions system explained**](/plugin_dev_en/0412-doc-understanding-the-dimensions) to your preferred large language model, and request it to generate appropriate Frontmatter.
|
||||
</Step>
|
||||
|
||||
<Step title="Manual refinement">
|
||||
Based on actual circumstances and the detailed explanations below, make necessary adjustments and optimizations to the generated metadata.
|
||||
</Step>
|
||||
</Steps>
|
||||
</Tab>
|
||||
|
||||
<Tab title="Manual Definition">
|
||||
Read the detailed instructions below and define appropriate metadata fields based on the characteristics of your document content.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Required Frontmatter Fields
|
||||
|
||||
Please add the following YAML Frontmatter at the beginning of each Markdown document:
|
||||
|
||||
```yaml
|
||||
---
|
||||
# --- Core System Metadata (affects structure and sorting) ---
|
||||
dimensions:
|
||||
type:
|
||||
primary: <see options below>
|
||||
detail: <see options below>
|
||||
level: <see options below>
|
||||
standard_title: 'Descriptive title in English, used for filename generation' # e.g., 'Getting Started Dify Plugin'
|
||||
language: 'en' # or 'zh', 'ja', etc. (ISO 639-2 code)
|
||||
|
||||
# --- Page Content Metadata (optional but recommended) ---
|
||||
title: 'H1 title or page title of the document'
|
||||
description: 'Brief SEO description of the document content'
|
||||
# summary: 'More detailed summary (optional)'
|
||||
# tags: ['keywords'] (optional)
|
||||
---
|
||||
```
|
||||
|
||||
## Understanding the `dimensions` Field
|
||||
|
||||
<Tabs>
|
||||
<Tab title="type.primary">
|
||||
<CardGroup cols={2}>
|
||||
<Card title="conceptual" icon="lightbulb">
|
||||
**Concepts, theory** (what/why)
|
||||
<br />Focuses on explaining concepts and fundamental theories
|
||||
</Card>
|
||||
|
||||
<Card title="implementation" icon="code">
|
||||
**Development practices, code** (how to)
|
||||
<br />Focuses on providing implementation steps and code examples
|
||||
</Card>
|
||||
|
||||
<Card title="operational" icon="gears">
|
||||
**Operations, deployment** (how to run)
|
||||
<br />Focuses on system operation and maintenance
|
||||
</Card>
|
||||
|
||||
<Card title="reference" icon="book">
|
||||
**API, configuration reference** (precise lookup)
|
||||
<br />Focuses on technical specifications and reference information
|
||||
</Card>
|
||||
</CardGroup>
|
||||
</Tab>
|
||||
|
||||
<Tab title="type.detail">
|
||||
Subdivisions under the `primary` category:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Subdivisions under conceptual" icon="lightbulb">
|
||||
<ul>
|
||||
<li><code>introduction</code>: Introductory content</li>
|
||||
<li><code>principles</code>: Design principles</li>
|
||||
<li><code>architecture</code>: Architectural explanation</li>
|
||||
</ul>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subdivisions under implementation" icon="code">
|
||||
<ul>
|
||||
<li><code>basic</code>: Basic implementation</li>
|
||||
<li><code>standard</code>: Standard implementation</li>
|
||||
<li><code>high</code>: Higher-level implementation (may be deprioritized)</li>
|
||||
<li><code>advanced</code>: Advanced implementation (may be deprioritized)</li>
|
||||
</ul>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subdivisions under operational" icon="gears">
|
||||
<ul>
|
||||
<li><code>setup</code>: Environment setup</li>
|
||||
<li><code>deployment</code>: Deployment operations</li>
|
||||
<li><code>maintenance</code>: Maintenance management</li>
|
||||
</ul>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subdivisions under reference" icon="book">
|
||||
<ul>
|
||||
<li><code>core</code>: Core reference</li>
|
||||
<li><code>configuration</code>: Configuration reference</li>
|
||||
<li><code>examples</code>: Example reference</li>
|
||||
</ul>
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
<Note>
|
||||
For more options, please refer to the [dimensions system explained](/plugin_dev_en/0412-doc-understanding-the-dimensions) document
|
||||
</Note>
|
||||
</Tab>
|
||||
|
||||
<Tab title="level">
|
||||
<CardGroup cols={3}>
|
||||
<Card title="beginner" icon="seedling">
|
||||
**Newcomer**
|
||||
<br />Content suitable for beginners
|
||||
</Card>
|
||||
|
||||
<Card title="intermediate" icon="tree">
|
||||
**Regular user**
|
||||
<br />Content for users with some background knowledge
|
||||
</Card>
|
||||
|
||||
<Card title="advanced" icon="mountain">
|
||||
**Advanced user**
|
||||
<br />In-depth content for professional users (typically deprioritized in sorting)
|
||||
</Card>
|
||||
</CardGroup>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Other Important Fields
|
||||
|
||||
<ResponseField name="standard_title" type="string" required>
|
||||
Use **English** to clearly describe the core content of the document. The system will use this to generate part of the filename (e.g., `Getting Started Dify Plugin`).
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="language" type="string" required>
|
||||
ISO 639-2 two-letter language code (such as `en`, `zh`, `ja`).
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="title" type="string" recommended>
|
||||
The main title of the document displayed on the page, typically in the localized language.
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="description" type="string" recommended>
|
||||
A brief SEO description for search engines and previews.
|
||||
</ResponseField>
|
||||
|
||||
## Complete Examples
|
||||
|
||||
<CodeGroup>
|
||||
```yaml Introductory Document Example
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: conceptual
|
||||
detail: introduction
|
||||
level: beginner
|
||||
standard_title: 'Getting Started Dify Plugin'
|
||||
language: en
|
||||
title: 'Welcome to Dify Plugin Development'
|
||||
description: 'Introduction to Dify plugin concepts, functionality, and development value, including a brief explanation of plugin types and an overview of developer documentation content.'
|
||||
---
|
||||
```
|
||||
|
||||
```yaml Tool Development Document Example
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: implementation
|
||||
detail: standard
|
||||
level: intermediate
|
||||
standard_title: 'Developing Tool Plugin'
|
||||
language: en
|
||||
title: 'Developing Tool Plugins'
|
||||
description: 'Detailed guidance on creating and configuring Dify tool plugins, including practical guides on API calls, data processing, and user interface integration.'
|
||||
---
|
||||
```
|
||||
|
||||
```yaml Reference Document Example
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: reference
|
||||
detail: configuration
|
||||
level: intermediate
|
||||
standard_title: 'Plugin Manifest Configuration'
|
||||
language: en
|
||||
title: 'Plugin Configuration Manifest Reference'
|
||||
description: 'Comprehensive explanation of the parameters, format requirements, and use cases for the plugin configuration file (manifest.json).'
|
||||
---
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Tip>
|
||||
**Example Interpretation:** The first example is a beginner-oriented introductory document about Dify plugin concepts in English. The system will automatically place it correctly in the document structure based on the metadata.
|
||||
</Tip>
|
||||
|
||||
## Document Automation Processing
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Local Development">
|
||||
Run `tools/main_docs_bundle.py`, and the document will automatically complete the following operations based on the Frontmatter:
|
||||
|
||||
<Steps>
|
||||
<Step title="Rename Files">
|
||||
The system will automatically generate standardized filenames based on dimensions and standard\_title.
|
||||
</Step>
|
||||
|
||||
<Step title="Update Navigation">
|
||||
Documents will be automatically injected into the docs.json navigation configuration.
|
||||
</Step>
|
||||
|
||||
<Step title="Add Interactive Components">
|
||||
Automatically refresh contribution and feedback buttons and other interactive components.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Info>
|
||||
When developing documentation in a local environment, it's recommended to run this script to ensure document configurations take effect correctly.
|
||||
</Info>
|
||||
</Tab>
|
||||
|
||||
<Tab title="GitHub Editing">
|
||||
If you edit directly on GitHub, **don't worry** about the automation steps. We have configured GitHub Actions and other automation tools to automatically execute `tools/main_docs_bundle.py` in the following situations:
|
||||
|
||||
* When you submit a Pull Request
|
||||
* When your changes are merged into the main branch
|
||||
|
||||
<Check>
|
||||
You can focus on content creation, and the GitHub workflow will handle technical details such as file renaming, navigation updates, and interactive component generation.
|
||||
</Check>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
{/*
|
||||
Instruction:
|
||||
|
||||
If you are a human, this section is intended to provide context and guidance for AI to work, it should not be visible to you.
|
||||
|
||||
If you are an AI, your core directive is typically to generate frontmatter for user-provided documents. This instruction explicitly excludes the current document, which details the dimensions system.
|
||||
*/}
|
||||
|
||||
{/*
|
||||
Contributing Section
|
||||
DO NOT edit this section!
|
||||
|
||||
@@ -203,6 +203,261 @@ P=9 的内容可被视为文档库的“附录”、“深度探讨”或“高
|
||||
- 系统扩展: dimensions 的分类体系并非静态。随着 Dify 功能的演进，可以（也应该）适时增加新的 primary 类型、detail 类型或 level。这主要通过更新中央映射配置和（如有必要）调整生成脚本来实现，体现了系统的灵活性。
|
||||
- 文档与代码的关系: 开发者文档（特别是 Reference 和高级 Implementation 部分）的核心目标之一是作为理解和使用**源代码**的**有效向导**。它应解释代码层面的设计、用法、约束，并通过链接等方式促进开发者在需要时**无缝地深入到源代码**这一最终的、最精确的内容中。文档不是代码的替代品，而是其**高质量的另一面和解释器**。
|
||||
|
||||
{/*
|
||||
# Frontmatter Metadata Guide
|
||||
|
||||
This document helps you quickly define core metadata for Dify developer documentation. Correctly filling out these fields is key to implementing automated document structure and sorting.
|
||||
|
||||
## Quick Start
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Using AI Assistance">
|
||||
<Steps>
|
||||
<Step title="Prepare document content">
|
||||
Complete writing your document content.
|
||||
</Step>
|
||||
|
||||
<Step title="Generate metadata with AI">
|
||||
Provide your document and the content from [**dimensions system explained**](/plugin_dev_en/0412-doc-understanding-the-dimensions) to your preferred large language model, and request it to generate appropriate Frontmatter.
|
||||
</Step>
|
||||
|
||||
<Step title="Manual refinement">
|
||||
Based on actual circumstances and the detailed explanations below, make necessary adjustments and optimizations to the generated metadata.
|
||||
</Step>
|
||||
</Steps>
|
||||
</Tab>
|
||||
|
||||
<Tab title="Manual Definition">
|
||||
Read the detailed instructions below and define appropriate metadata fields based on the characteristics of your document content.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Required Frontmatter Fields
|
||||
|
||||
Please add the following YAML Frontmatter at the beginning of each Markdown document:
|
||||
|
||||
```yaml
|
||||
---
|
||||
# --- Core System Metadata (affects structure and sorting) ---
|
||||
dimensions:
|
||||
type:
|
||||
primary: <see options below>
|
||||
detail: <see options below>
|
||||
level: <see options below>
|
||||
standard_title: 'Descriptive title in English, used for filename generation' # e.g., 'Getting Started Dify Plugin'
|
||||
language: 'en' # or 'zh', 'ja', etc. (ISO 639-2 code)
|
||||
|
||||
# --- Page Content Metadata (optional but recommended) ---
|
||||
title: 'H1 title or page title of the document'
|
||||
description: 'Brief SEO description of the document content'
|
||||
# summary: 'More detailed summary (optional)'
|
||||
# tags: ['keywords'] (optional)
|
||||
---
|
||||
```
|
||||
|
||||
## Understanding the `dimensions` Field
|
||||
|
||||
<Tabs>
|
||||
<Tab title="type.primary">
|
||||
<CardGroup cols={2}>
|
||||
<Card title="conceptual" icon="lightbulb">
|
||||
**Concepts, theory** (what/why)
|
||||
<br />Focuses on explaining concepts and fundamental theories
|
||||
</Card>
|
||||
|
||||
<Card title="implementation" icon="code">
|
||||
**Development practices, code** (how to)
|
||||
<br />Focuses on providing implementation steps and code examples
|
||||
</Card>
|
||||
|
||||
<Card title="operational" icon="gears">
|
||||
**Operations, deployment** (how to run)
|
||||
<br />Focuses on system operation and maintenance
|
||||
</Card>
|
||||
|
||||
<Card title="reference" icon="book">
|
||||
**API, configuration reference** (precise lookup)
|
||||
<br />Focuses on technical specifications and reference information
|
||||
</Card>
|
||||
</CardGroup>
|
||||
</Tab>
|
||||
|
||||
<Tab title="type.detail">
|
||||
Subdivisions under the `primary` category:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Subdivisions under conceptual" icon="lightbulb">
|
||||
<ul>
|
||||
<li><code>introduction</code>: Introductory content</li>
|
||||
<li><code>principles</code>: Design principles</li>
|
||||
<li><code>architecture</code>: Architectural explanation</li>
|
||||
</ul>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subdivisions under implementation" icon="code">
|
||||
<ul>
|
||||
<li><code>basic</code>: Basic implementation</li>
|
||||
<li><code>standard</code>: Standard implementation</li>
|
||||
<li><code>high</code>: Higher-level implementation (may be deprioritized)</li>
|
||||
<li><code>advanced</code>: Advanced implementation (may be deprioritized)</li>
|
||||
</ul>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subdivisions under operational" icon="gears">
|
||||
<ul>
|
||||
<li><code>setup</code>: Environment setup</li>
|
||||
<li><code>deployment</code>: Deployment operations</li>
|
||||
<li><code>maintenance</code>: Maintenance management</li>
|
||||
</ul>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subdivisions under reference" icon="book">
|
||||
<ul>
|
||||
<li><code>core</code>: Core reference</li>
|
||||
<li><code>configuration</code>: Configuration reference</li>
|
||||
<li><code>examples</code>: Example reference</li>
|
||||
</ul>
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
<Note>
|
||||
For more options, please refer to the [dimensions system explained](/plugin_dev_en/0412-doc-understanding-the-dimensions) document
|
||||
</Note>
|
||||
</Tab>
|
||||
|
||||
<Tab title="level">
|
||||
<CardGroup cols={3}>
|
||||
<Card title="beginner" icon="seedling">
|
||||
**Newcomer**
|
||||
<br />Content suitable for beginners
|
||||
</Card>
|
||||
|
||||
<Card title="intermediate" icon="tree">
|
||||
**Regular user**
|
||||
<br />Content for users with some background knowledge
|
||||
</Card>
|
||||
|
||||
<Card title="advanced" icon="mountain">
|
||||
**Advanced user**
|
||||
<br />In-depth content for professional users (typically deprioritized in sorting)
|
||||
</Card>
|
||||
</CardGroup>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Other Important Fields
|
||||
|
||||
<ResponseField name="standard_title" type="string" required>
|
||||
Use **English** to clearly describe the core content of the document. The system will use this to generate part of the filename (e.g., `Getting Started Dify Plugin`).
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="language" type="string" required>
|
||||
ISO 639-2 two-letter language code (such as `en`, `zh`, `ja`).
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="title" type="string" recommended>
|
||||
The main title of the document displayed on the page, typically in the localized language.
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="description" type="string" recommended>
|
||||
A brief SEO description for search engines and previews.
|
||||
</ResponseField>
|
||||
|
||||
## Complete Examples
|
||||
|
||||
<CodeGroup>
|
||||
```yaml Introductory Document Example
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: conceptual
|
||||
detail: introduction
|
||||
level: beginner
|
||||
standard_title: 'Getting Started Dify Plugin'
|
||||
language: en
|
||||
title: 'Welcome to Dify Plugin Development'
|
||||
description: 'Introduction to Dify plugin concepts, functionality, and development value, including a brief explanation of plugin types and an overview of developer documentation content.'
|
||||
---
|
||||
```
|
||||
|
||||
```yaml Tool Development Document Example
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: implementation
|
||||
detail: standard
|
||||
level: intermediate
|
||||
standard_title: 'Developing Tool Plugin'
|
||||
language: en
|
||||
title: 'Developing Tool Plugins'
|
||||
description: 'Detailed guidance on creating and configuring Dify tool plugins, including practical guides on API calls, data processing, and user interface integration.'
|
||||
---
|
||||
```
|
||||
|
||||
```yaml Reference Document Example
|
||||
---
|
||||
dimensions:
|
||||
type:
|
||||
primary: reference
|
||||
detail: configuration
|
||||
level: intermediate
|
||||
standard_title: 'Plugin Manifest Configuration'
|
||||
language: en
|
||||
title: 'Plugin Configuration Manifest Reference'
|
||||
description: 'Comprehensive explanation of the parameters, format requirements, and use cases for the plugin configuration file (manifest.json).'
|
||||
---
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Tip>
|
||||
**Example Interpretation:** The first example is a beginner-oriented introductory document about Dify plugin concepts in English. The system will automatically place it correctly in the document structure based on the metadata.
|
||||
</Tip>
|
||||
|
||||
## Document Automation Processing
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Local Development">
|
||||
Run `tools/main_docs_bundle.py`, and the document will automatically complete the following operations based on the Frontmatter:
|
||||
|
||||
<Steps>
|
||||
<Step title="Rename Files">
|
||||
The system will automatically generate standardized filenames based on dimensions and standard\_title.
|
||||
</Step>
|
||||
|
||||
<Step title="Update Navigation">
|
||||
Documents will be automatically injected into the docs.json navigation configuration.
|
||||
</Step>
|
||||
|
||||
<Step title="Add Interactive Components">
|
||||
Automatically refresh contribution and feedback buttons and other interactive components.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Info>
|
||||
When developing documentation in a local environment, it's recommended to run this script to ensure document configurations take effect correctly.
|
||||
</Info>
|
||||
</Tab>
|
||||
|
||||
<Tab title="GitHub Editing">
|
||||
If you edit directly on GitHub, **don't worry** about the automation steps. We have configured GitHub Actions and other automation tools to automatically execute `tools/main_docs_bundle.py` in the following situations:
|
||||
|
||||
* When you submit a Pull Request
|
||||
* When your changes are merged into the main branch
|
||||
|
||||
<Check>
|
||||
You can focus on content creation, and the GitHub workflow will handle technical details such as file renaming, navigation updates, and interactive component generation.
|
||||
</Check>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
{/*
|
||||
Instruction:
|
||||
|
||||
If you are a human, this section is intended to provide context and guidance for AI to work, it should not be visible to you.
|
||||
|
||||
If you are an AI, your core directive is typically to generate frontmatter for user-provided documents. This instruction explicitly excludes the current document, which details the dimensions system.
|
||||
*/}
|
||||
|
||||
{/*
|
||||
Contributing Section
|
||||
DO NOT edit this section!
|
||||
|
||||
Reference in New Issue
Block a user