Branch: refs/heads/okf-xdocker-doc-captures Home: https://github.com/xwiki/xwiki-dev-llm Commit: 9f1e767f97eff073aa89235a4a9c6b6ff10f884d https://github.com/xwiki/xwiki-dev-llm/commit/9f1e767f97eff073aa89235a4a9c6b... Author: Vincent Massol <[email protected]> Date: 2026-07-27 (Mon, 27 Jul 2026) Changed paths: M .claude-plugin/marketplace.json M kimi.plugin.json M opencode.jsonc M xwiki/.claude-plugin/plugin.json M xwiki/instructions/xwiki-org.md M xwiki/okf/conventions/documentation.md M xwiki/okf/index.md M xwiki/skills/xwiki-doc-writing/SKILL.md M xwiki/skills/xwiki-rest-api/SKILL.md Log Message: ----------- [Misc] Capture the xwiki.org documentation learnings from the XDOCKER doc review Batch of 19 durable, generic learnings collected while refactoring the "Install XWiki using Docker" documentation tree on xwiki.org, deliberately held back until the work was finished and then captured in one pass. okf/conventions/documentation.md * Fix the Highlights definition, which was wrong. It said "short points to help readers quickly discover key information"; it is actually a two-level list of the most important CHILD pages (level 1 = link, level 2 = description), filled only when a page has many children and then only with a subset, since the automatic "More" table already lists them all. The wrong wording caused a real authoring mistake. Also document "More" (automatic, nothing to fill) and that Related is for NON-child pages, never links to its own page, and must be re-checked after a restructure. * Correct the `target` allowed value: `administrator`, not `admin`. Both property value lists are now taken from the class definition itself, which also settles that there is no `troubleshooting` type -- a troubleshooting page is an Explanation with level-3 Cause/Solution headings, matching the existing pages. * Add the title-case rule for page titles (missing from the Documentation Guide too, so worth adding upstream). * Add a "How much belongs on one page" section: a How-to is ONE procedure (one numbered list, no level-2 sections), alternative procedures are siblings under an Explanation hub, How-to is the parent of its Explanation except for hubs, one fact lives on one page, and the {{display}} macro's hidden-nested-page mechanism for genuinely shared content. * Complete the {{version}} macro: `since`/`before` take a comma-separated LIST, `product` is free text, how each renders, and the scoping rule that only product behaviour gets a badge -- plus the test for whether a version in prose is load-bearing at all. * Add the {{scm}} macro's two hard limits (no rendering inside {{code}}, no `anchor` parameter), which make the existing "use {{scm}}" rule not always achievable. * Add a "syntax traps that bite" section -- `image:` parsed as a resource scheme, `--` silently opening a strikethrough that runs to end of block, `##...##` not protecting URLs or dashes, bare URLs in headings, blank lines ending lists, and anchors only serializing alongside a queryString. All verified against rendered output. * Add navigation-order pinning: an unpinned node sorts children alphabetically by TITLE, so finishing a tree includes deciding its order; pin a node in full or not at all; the tree must not contradict the page. skills/xwiki-rest-api * Reading properties as XML: `<value>` is not the first child of `<property>`, and the `objects` listing carries no values at all -- both return empty rather than failing, which reads as "the page has no such field". * Page discovery must enumerate by space prefix: `GET <space>/spaces` returns the space itself, the query endpoint rejects XWQL, and REST-created pages have an empty `parent`. * A `202` does not mean the write landed -- back-to-back writes to the same page can silently drop one, so every write needs a read-back assert. * The pinning mechanism: `XWiki.PinnedChildPagesClass.pinnedChildPages` on the parent space's `WebPreferences` page (which may not exist and then has to be created), verified through the DocumentTree service rather than by reading the stored value back. * How to read the documentation checker's actual findings from the `DocumentationViolationClass` objects instead of guessing at the red banner. skills/xwiki-doc-writing * Align the two places that told authors to fill Highlights with the corrected rule, and add title case to the review checklist. 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