Dify Docs Format Check

Formatting Check (en / zh / ja)

Read-only audit of documentation formatting. Mechanical rules are enforced by two linter scripts in this skill directory; judgment-call rules are checked by reading each file. Route by path:

Procedure

1. Read the rule sources for the languages in scope. The digests in steps 4-5 are summaries of these files; wherever a digest and its source disagree, the source file wins.

   • writing-guides/formatting-guide.md — all languages
   • tools/translate/formatting-zh.md — when any zh/ file is in scope
   • tools/translate/formatting-ja.md — when any ja/ file is in scope

2. Detect the files to audit. Audit entire files, not just diffs. Default to the files currently under review:

   git diff --name-only; git diff --cached --name-only; git status --porcelain | grep '^??'

   Keep .mdx/.md files under en/, zh/, or ja/. If none are detected, ask the user which files to check. Translations ship as a zh/ja pair from one English source, so when both changed, audit both in the same session.

3. Run the linter for each path group and paste its output verbatim into your report:

   python3 .claude/skills/dify-docs-format-check/check-format-en.py <en files...>
   python3 .claude/skills/dify-docs-format-check/check-format-cjk.py <zh and ja files...>

   Success signal: each run prints one block per file and ends with Total violations: {n}; exit code is 0 when n = 0, 1 otherwise. A file passed to the wrong script is skipped with a stderr note (skip (non-en) / skip (non-zh/ja)); check-format-cjk.py selects the zh or ja rule set from the file path.

   Then check that the three languages carry the same structure, passing every page in scope whatever its language (a zh or ja path is checked through its English twin):

   python3 tools/check-parity.py --base origin/main <changed pages...>

   Success signal: PARITY OK: {n} pages; otherwise one line per new mismatch and PARITY ISSUES: {n}, exit 1. The check compares each English page with its twins by path: heading count and level, then per section the paragraphs, list items, code blocks, table rows, the sequence of components, and anchor ids. Heading text is not compared, and the translation disclaimer is skipped. Mismatches already present at the base ref are listed under pre-existing and do not fail the run, because much of the corpus predates this check; report them to the owner with the other pre-existing findings.

   The scripts are the authoritative deterministic rule list. Violation lines print as line [rule-id] message and the messages are self-describing, so do not re-summarize each rule. Rule-ID families: F- frontmatter, H- headings, B- bold/italic, L- lists, C- code, Li- links, I- images, M- Mintlify components, U- UI element references (en only), S- spacing, P- punctuation, CJK- both CJK languages, ZH- Chinese only, JA- Japanese only.

   Five IDs need context the message alone does not give:

   • H-ing-verb (en): section-name gerunds (Troubleshooting, Logging, Getting Started, etc.) are exempt via the SKIP_ING_HEADINGS constant in check-format-en.py. If a flagged heading is a legitimate section concept, propose the addition to SKIP_ING_HEADINGS in your report — do not edit the script.
   • I-alt-empty (en): flags every empty alt as a prompt to confirm the image is genuinely decorative, not as a hard error.
   • CJK-disclaimer-missing: the script looks for the translation disclaimer only within the ~10 lines below the frontmatter, so a disclaimer placed lower in the file still trips it. Pages whose frontmatter sets mode: "custom" or mode: "frame" are exempt — chrome-less landing pages carry no disclaimer (see the formatting guides' Translation Disclaimer exception).
   • CJK-cross-lang-link: /en/... links are flagged everywhere except on the disclaimer line, which is allowed to point at the English source.
   • CJK-latin-spacing: on lines with an even number of ** markers, the script skips every complete bold span, not only UI labels. Manually check each bold span with CJK and Latin/digit adjacency: a literal UI label preserves the product's spacing; emphasized prose needs the normal space. Lines with an odd number of ** markers remain fully checked after code and URLs are stripped. Non-bold quoted labels are not exempt.

   When changing the CJK checker, run python3 .claude/skills/dify-docs-format-check/test_check_format_cjk.py. The regression suite must end with OK and exit 0.

4. Judgment review — en/ files. Digest of writing-guides/formatting-guide.md (section names in parentheses; the guide wins on conflict). Read each file and check:

   • Headings (§Headings): proper title case — major words capitalized, minor words (a, and, the, of, in, on, to, etc.) lowercase except at the start. Flag sentence case, all-lowercase, or inconsistency.
   • Bold and emphasis (§Bold and Italic, §Quotation Marks): bold only for UI elements, menu paths, tab/field names, and first-use key terms; running-text emphasis is italic or restructured. Flag "word" used emphatically rather than as a quotation or literal-phrase reference.
   • Lists (§Lists): numbered lists only for sequential steps, otherwise dashes; labeled-concept items use - **Label**: description.; items are all sentences (period) or all fragments (no period), never mixed; child content (description, callout, image) indented two spaces under its item.
   • Links (§Links): descriptive link text — flag vague text (this page, here) even when it isn't click here exactly.
   • Images (§Images: Alt Text, Captions, Storage, Naming): alt text in title case describing what the image communicates ("LLM Node Configuration Panel", not "Screenshot of a form"); comparison images shown together each need a caption (the linter cannot detect adjacency); alt="" only for genuinely decorative images; storage path follows the /images/<tier-1>/<tier-2>/... taxonomy; filenames descriptive and specific (workflow-llm-node-parameters.png, not screenshot.png).
   • Tables (§Tables): left-aligned with :---; bold in header row only when it aids clarity; multi-line cells prefer lists or components, falling back to <br/> only when a manual break is unavoidable.
   • Mintlify components (§Mintlify Components): content inside <Info>, <Note>, etc. reads cleanly (bold, links work as expected).

5. Judgment review — zh/ and ja/ files. Digest of tools/translate/formatting-zh.md and tools/translate/formatting-ja.md (those files win on conflict). The two findings the linter misses most often are translated anchor slugs and {{placeholder}} variables left unchanged in otherwise-translated prompts. Read each file and check:

   • Translatable elements (§Translatable Elements, both files): Tab titles (<Tab title="...">), Frame captions, and image alt text translated; bold UI labels translated; natural-language prompt examples inside code blocks translated with variable placeholders ({{variable_name}}) left unchanged.
   • Anchors (§Cross-Reference Anchors, both files): [text](#anchor) and [text](/path#anchor) use the translated heading slug — the heading ## 响应 produces #响应, not #response. Exception: a target heading or tab carrying an explicit stable ID ({#stable-id}, Tab id, or <a id>) is linked by that English ID in every language — check the target before flagging an English anchor.
   • Chinese style (formatting-zh.md): enumeration comma 、 for parallel items within a sentence (§Enumeration Comma); ellipsis …… used correctly and not combined with 等 in one phrase (§Ellipsis); Arabic numerals for technical content (3 种, not 三种) with idiomatic expressions as the judgment call (§Numbers); translationese — redundant 你的, unnecessary 会, 当...时 wrappers, 能够 for 能, 可以 where 可 suffices (§Translation Quality → Patterns to Eliminate).
   • Japanese style (formatting-ja.md): です/ます maintained in body text (§Writing Style, §Honorifics); headings are noun phrases, not sentences (§Headings); short loanwords (3 morae or fewer) keep the trailing ー, longer ones drop it, and established compounds (ワークフロー, ナレッジベース) match the glossary (§Katakana Conventions); middle dot ・ only where readability needs it, none inside established compounds (§Middle Dot); translationese — redundant あなたの, 〜することができます for 〜できます, 〜とき/〜場合 wrappers, stacked の (§Translation Quality → Patterns to Eliminate).

6. Report. Paste the raw linter output first, then append judgment findings per file:

   [linter output, verbatim — per file: "### {path}" (the cjk script adds
   " ({lang})"), then "line [rule-id] message" lines or "✅ no deterministic
   issues found", each run ending with "Total violations: {n}"]
   
   ### Judgment findings
   
   **{path}**
   - Line {n}: {description of issue} ({rule area})

   The scripts report only violations; do not invent per-rule "clean" lines they never printed. A file with no violations and no judgment findings needs nothing beyond its ✅ no deterministic issues found line.