Branch: refs/heads/doc-linter-visual-rules Home: https://github.com/xwiki/xwiki-dev-llm Commit: cf0840580d409acabddc1afa9d4ef648b3a67f73 https://github.com/xwiki/xwiki-dev-llm/commit/cf0840580d409acabddc1afa9d4ef6... Author: Vincent Massol <[email protected]> Date: 2026-09-04 (Fri, 04 Sep 2026) Changed paths: M .gitignore M xwiki/okf/conventions/documentation.md M xwiki/skills/xwiki-doc-writing/SKILL.md M xwiki/skills/xwiki-doc-writing/tools/README.md M xwiki/skills/xwiki-doc-writing/tools/docpages.py Log Message: ----------- [Misc] Close the doc linter's blind spots on visuals * strip_verbatim now drops complete inline `{{code}}`/`{{plantuml}}` pairs from a line before deciding whether the line opens a block. The house style writes an inline `{{code}}man{{/code}}` in most paragraphs, and the scanner treated one as an opener that never closed, blanking the rest of the field from every check: false "declared but not referenced" on images two lines below, and real defects on those lines hidden — a broken `{{gallery}}` whose five image links resolved to nothing passed lint because of it * The result-step and step-ratio rules are now type-scoped: a Developer page is asked for a code example, not a screenshot of a UI it does not have. That is what left a correct Developer How-to permanently reported as broken, with no fix but padding it with screenshots * New advisory rule: an Explanation that is not a hub and carries no diagram, image or code example at all. The guide's "do not force it" stays explicit, so it is advisory by design and hub pages are exempt — their job is routing * verify now proves a `{{plantuml}}` diagram actually rendered. The macro renders asynchronously, so the first HTML holds only `<div class="xwiki-async">` and neither rendering-error marker can ever fire on a diagram: a page could be published with a diagram that shows nothing and pass every check. It re-fetches until the macro output is inlined, then fetches the image * The review checklist says how it is applied — page by item, recording the items that came back clean — so "not looked at" stops reading like "no finding"; and "Shows, not only tells" splits into three type-scoped items plus a gratuitous-visual one, since as one item it was satisfied by whichever visual happened to be present * The OKF's diagram rule gains a decidable trigger (component structure, request or data flow, lifecycle, decision between alternatives — and the three shapes that need none) instead of one bullet followed by "do not force it"; and the `{{image}}` bullet records that xwiki.org renders the file name in place of the stored `alt`, on every page of the tree * Verified against the 37 published MCP Server pages: lint goes from 8 problems (6 of them strip_verbatim artifacts, 2 unfixable Developer-page findings) to 1 real advisory one, and the new verify pass fetches all three of the tree's PlantUML diagrams — proven by asserting it reports 1/2 when told to expect two. validate.mjs OK, version untouched Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> To unsubscribe from these emails, change your notification settings at https://github.com/xwiki/xwiki-dev-llm/settings/notifications