Check formatting compliance in changed English documentation against writing-guides/formatting-guide.md. Use after finalizing a draft, or when the user says "check formatting", "format audit", "format check" on English content.
Verify changed English documentation against every rule in writing-guides/formatting-guide.md. Mechanical rules are enforced by a linter script (check-format-en.py); judgment-call rules are checked by reading the file.
Detect changed documentation files by combining:
git diff --name-only (unstaged changes in tracked files)git diff --cached --name-only (staged changes)git status --porcelain (lines starting with ??)Filter for .mdx and .md files under en/. If no changed files are detected, ask the user which files to check.
Run the linter and capture its output:
python3 .claude/skills/dify-docs-format-check-en/check-format-en.py <file> [<file> ...]
The script checks these rules. Each violation includes the file path, line number, rule ID, severity, and a short message.
Frontmatter
F-title-missing — file lacks title field.F-desc-trailing-period — description ends with a period.F-quote-needed — value contains : (colon + space) but is not quoted.F-quote-unnecessary — value is quoted but contains no character that requires quoting.F-single-quote — value uses single quotes; should use double.F-blank-after-fm — no blank line between closing --- and body.Headings
H-trailing-hash — heading ends with a trailing #.H-blank-before / H-blank-after — missing blank line adjacent to a heading.H-skip-level — jump in depth (e.g., H2 to H4 without H3).H-ing-verb — heading starts with a verb in -ing form where the base form should be used. The linter carries a curated verb list and strips leading numeric/parenthetical prefixes (1., (a), etc.) before detection. Section-name gerunds in a skip list are not flagged (Troubleshooting, Logging, Getting Started, Monitoring Data List, etc.). The skip list lives in the script constant SKIP_TEXTS.Bold and Italic
B-trailing-colon-inside — **X:** or **X:** patterns. Colon must be outside the bold markers.B-underscore-italic — _italic_ style; must use *italic*.Lists
L-asterisk-bullet — * used as a bullet; must use - .L-blank-before / L-blank-after — missing blank line around a list block.L-nested-indent — nested list item not indented by a multiple of 2 spaces.Code
C-no-language — fenced code block opens with ``` but no language tag.C-blank-before / C-blank-after — missing blank line around a fenced code block.Links
Li-click-here — link text is click here, here, or Click here.Li-http-external — external link uses http:// rather than https://.Li-internal-no-prefix — internal link starts with a relative path or omits the language prefix (/en/...).Images
I-raw-img-tag — raw <img> element used instead of <Frame> + markdown.I-alt-empty —  with no alt text on a non-decorative image. The script flags every empty alt as a prompt to confirm the image is truly decorative.I-alt-too-long — alt text exceeds 125 characters.I-caption-alt-mismatch — <Frame caption="..."> value differs from the alt text of the enclosed markdown image.I-filename-uppercase-ext — filename ends with an uppercase extension (.PNG, .JPG).I-filename-retina-suffix — filename contains @2x, @3x, or similar.I-filename-default-tool — filename begins with CleanShot, Screenshot, IMG_, etc.I-filename-non-kebab — filename has underscores, spaces, uppercase letters, or non-ASCII characters.I-filename-ing-verb — filename begins with a verb in -ing form.Mintlify Components
M-tab-no-title — <Tab> without a title attribute.M-component-blank-before / M-component-blank-after — missing blank line around <Info>, <Tip>, <Note>, or <Warning>.UI Element References
U-menu-arrow — menu path uses →, ->, or => instead of >.Spacing
S-double-blank — two or more consecutive blank lines.S-trailing-whitespace — line ends with whitespace.Punctuation
P-em-dash-spaces — em dash — surrounded by spaces.P-en-dash-spaces — en dash – surrounded by spaces in a numeric range.P-fullwidth-in-english — full-width punctuation (,。;:!?()、) adjacent to ASCII letters.For each changed file, read it and look for:
Headings
a, and, the, of, in, on, to, etc.) lowercase except at the start. Flag any heading that reads as sentence case, all-lowercase, or inconsistent.Bold and emphasis
"word" patterns used emphatically (not as direct quotations or literal-phrase references).Lists
- **Label**: description. A list where each item introduces a labeled concept should use this pattern.Links
this page, here) even when it isn't click here exactly.Images
alt="" should be used only for images that carry no information. Confirm that any empty alt flagged by the linter is truly decorative./images/<tier-1>/<tier-2>/... follows the content-domain taxonomy in the guide.workflow-llm-node-parameters.png, not workflow-01.png or screenshot.png).Tables
:---; bold used in header row only when it aids clarity.<br/><br/><br/><br/> when a manual break is unavoidable.General
<Info>, <Note>, etc.).## English Formatting Check Results
### File: {path}
**Deterministic violations** ({n})
- Line {n} [{rule-id}]: {message}
- ...
**Judgment-call findings** ({n})
- Line {n}: {description of issue} — {rule area}
- ...
**Clean checks**
- ✅ Frontmatter valid
- ✅ No deterministic violations in {area}
Group by file. If a file has no issues in any area, report a single ✅ line for it.
-ing verb that should have been in SKIP_TEXTS, or _ that is a legitimate filename/identifier), surface it as a finding but note the ambiguity so the user can decide.