Diagrams

Last modified by Vincent Massol on 2026/11/14 22:50

Whenever you need to add a diagram, you must:

This has several benefits:

  • Consistent diagram look and feel across xwiki.org
  • The source of the diagram is in the wiki content and thus can be easily modified (it wouldn't be the case with a screenshot of a generated diagram for example)
  • Makes it easier to edit diagrams as otherwise you would need to use the same tool as the one used by the person who generated the diagram to be modified (provided they attached the source to the page, see previous point)
  • Diagrams readable by everyone, including readers with low vision or on a poor screen

Accessible Colors

The bluegray theme alone does not meet WCAG 2.2 AA: it draws light text on light fills in every diagram type it renders. Every diagram must therefore carry the accessible palette:

  • Copy it from plantuml-accessible-palette.puml, attached to this page, and paste it verbatim, immediately under the !theme bluegray line, before the diagram itself.
  • Keep it byte for byte as it is: a modified copy is no longer the palette, and the next revision of it will not find yours.

Example:

  • URL Architecture 
  • Content:
    {{plantuml}}
    @startuml
    !theme bluegray
    ' ---- XWiki accessible diagram palette (WCAG 2.1 AA): paste verbatim under
    ' !theme bluegray. Canonical copy: xwiki-doc-writing/tools/ in xwiki-dev-llm.
    ' ... the rest of the palette, pasted verbatim ...
    ' ---- end XWiki accessible diagram palette ----
    start
    -> URL;
    :Routing Filter;
    floating note left
      Executed as the first
      Filter in web.xml
    end note
    if (Resource Reference Filter?) then (Yes)
      :Resource Reference Handler Servlet;
      :Resource Reference Handler;
      note: e.g. WebJarsResourceReferenceHandler
      kill
    else (No)
       :Evaluate rest of web.xml;
      kill
    endif
    @enduml
    {{/plantuml}}

Here are a few tools to help produce and test plantuml diagrams:

Get Connected