feat: add shared writing guides, documentation skills, and repo infrastructure#720
feat: add shared writing guides, documentation skills, and repo infrastructure#720
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
dosubot
bot
added
the
size:XXL
dosubot
bot
added
documentation
There was a problem hiding this comment.
Pull request overview
This PR sets up shared documentation authoring infrastructure for the Dify docs repo—centralizing style/formatting/terminology guidance, codifying Claude “skills” for common doc tasks, and adding tooling to keep the translation termbase derived from the glossary.
Changes:
- Add
writing-guides/(style guide, formatting guide, glossary, and an index that routes tasks to the right skill). - Add multiple
.claude/skills/for guides, API reference, env vars, release sync, and reader verification. - Add translation tooling docs + automation helpers (termbase derivation script, pre-commit hook, language-specific formatting guides, translation system overview).
Reviewed changes
Copilot reviewed 23 out of 23 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| writing-guides/style-guide.md | Defines voice/tone and writing patterns for docs. |
| writing-guides/index.md | Routes contributors to the correct skill and reference guides. |
| writing-guides/glossary.md | Establishes standardized terminology + UI labels (source of truth). |
| writing-guides/formatting-guide.md | Defines MDX/Mintlify formatting standards and component usage. |
| tools/translate/translation-system-overview.md | Documents the end-to-end translation pipeline architecture and workflows. |
| tools/translate/termbase_i18n.md | Expands/refactors the termbase content used by the translation engine. |
| tools/translate/formatting-zh.md | Adds Chinese-specific formatting rules for translations. |
| tools/translate/formatting-ja.md | Adds Japanese-specific formatting rules for translations. |
| tools/translate/derive-termbase.py | Adds generator to derive termbase_i18n.md from the rich glossary. |
| README.md | Adds contributor guide and repo usage conventions. |
| CLAUDE.md | Redesigns instructions into a concise task-routing hub. |
| .mintignore | Excludes internal guides/config from Mintlify build output. |
| .githooks/pre-commit | Auto-regenerates and stages the derived termbase when glossary changes. |
| .claude/skills/dify-docs-release-sync/SKILL.md | Adds a workflow for milestone-based pre-release doc synchronization. |
| .claude/skills/dify-docs-reader-test/SKILL.md | Adds a “reader persona” verification skill for post-writing review. |
| .claude/skills/dify-docs-guides/SKILL.md | Adds the primary user-guide writing/review skill referencing shared guides. |
| .claude/skills/dify-docs-env-vars/verify-env-docs.py | Adds a script to verify env-var docs against .env.example. |
| .claude/skills/dify-docs-env-vars/deep-dive.md | Adds a deep-dive reference for env var behavior and code trace notes. |
| .claude/skills/dify-docs-env-vars/SKILL.md | Adds env-var documentation process, conventions, and verification steps. |
| .claude/skills/dify-docs-api-reference/references/common-mistakes.md | Adds a quick-reference list of common OpenAPI spec issues. |
| .claude/skills/dify-docs-api-reference/references/codebase-paths.md | Adds mappings between docs/specs and Dify codebase locations. |
| .claude/skills/dify-docs-api-reference/references/audit-checklist.md | Adds a per-endpoint audit checklist for spec/code fidelity. |
| .claude/skills/dify-docs-api-reference/SKILL.md | Adds the main OpenAPI editing/auditing skill with strict fidelity rules. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| ### SECRET_KEY | ||
|
|
||
| **Default:** `sk-xxxx...xxxx` (pre-filled in .env.example; must be replaced for production) |
There was a problem hiding this comment.
This doc includes an sk-...-prefixed placeholder for SECRET_KEY (sk-xxxx...xxxx). The skill’s own style rules say to avoid sk-* patterns because they can trigger GitHub push protection / secret scanning. Consider rewriting the default example to avoid the sk- prefix entirely (while still explaining that it’s pre-filled and must be replaced).
| **Default:** `sk-xxxx...xxxx` (pre-filled in .env.example; must be replaced for production) | |
| **Default:** `secret-key-example-xxxx` (pre-filled in .env.example; must be replaced for production) |
| def parse_glossary(glossary_text: str) -> list[tuple[str, list[tuple[str, list[list[str]]]]]]: | ||
| """Parse glossary into top-level sections of (h2_heading, [(h3_heading, rows)]). | ||
|
|
||
| Each row is [English, Chinese, Japanese] with Notes/i18n Key stripped. | ||
| Capitalization markers (`*`) are stripped from English terms. | ||
| """ |
There was a problem hiding this comment.
parse_glossary() docstring says capitalization markers (*) are stripped from English terms, but the implementation never removes them. If the glossary starts using * markers, the generated termbase will include the markers and break terminology matching. Either implement the stripping on the English cell or update the docstring/comments to match actual behavior.
| ### Quick Start | ||
|
|
||
| 1. Fork and clone the repository. | ||
| 2. Create a branch, make your changes, and open a pull request against `main`. | ||
| 3. Your PR will be reviewed by a maintainer. Once approved, translations are generated automatically. | ||
|
|
There was a problem hiding this comment.
The repo adds a custom .githooks/pre-commit, but the README never tells contributors to enable it (e.g., via git config core.hooksPath .githooks). As-is, most clones won’t run the hook, so termbase_i18n.md can drift from writing-guides/glossary.md despite the new sync mechanism.
| PLACEHOLDER_PATTERNS = [ | ||
| "your-", "your_", "YOUR-", "YOUR_", | ||
| "xxx", "difyai", "dify-sandbox", | ||
| "sk-9f73s", "lYkiYYT6", "QaHbTe77", | ||
| "testaccount", "testpassword", "difypassword", | ||
| "gp-test.", "gp-ab", | ||
| "instance-name", | ||
| "WVF5YTha", | ||
| ] |
There was a problem hiding this comment.
PLACEHOLDER_PATTERNS includes a literal sk-... prefix (and other key-like fragments). Given the repo’s own guidance about push-protection / secret scanning for sk-*, hardcoding these strings can trigger false positives and is easy to forget to update. Prefer detecting placeholders by pattern (e.g., any value starting with sk-) rather than embedding example key prefixes.
Summary
writing-guides/with shared style guide, formatting guide, and trilingual glossary (with UI Labels section).claude/skills/:dify-docs-guides,dify-docs-api-reference,dify-docs-env-vars,dify-docs-release-sync,dify-docs-reader-testtools/translate/derive-termbase.py) and pre-commit hook (.githooks/) to keep glossary and termbase in synctools/translate/formatting-zh.md,formatting-ja.md)tools/translate/translation-system-overview.md)CLAUDE.mdas a concise task-routing hubREADME.mdwith contributor guideContext
Previously, three documentation skills (
dify-docs-writer,dify-openapi-standards,dify-env-var-docs) lived in a personal directory and maintained their own terminology, formatting rules, and style guidelines independently. This caused duplication and made team collaboration difficult.This PR establishes a unified system:
writing-guides/) serve as the single source of truth for style, formatting, and terminology