Using the Diagram Pro application

With this application you can edit and view diagrams in XWiki, using the diagrams.net integration.

You can create a big array of diagrams, such as: wireframes, mockups, UML, charts, BPMN, mind maps, tree & network diagrams etc.

Each diagram is stored in a wiki page. The revisions of the diagrams are synched in XWiki.

The app provides intuitive functionalities for both beginners and advanced users. You can:

• add and edit new diagrams, with a variety of shapes available

  

• import existing diagrams

  

• view the diagrams as images attached to wiki pages

  

• import diagrams from Gliffy

   

• include diagrams in other wiki pages

To learn more about how to create, edit and include diagrams on other wiki pages please visit the documentation tab

Examples

Create a diagram representing a logical structure

The Active Directory logical structure (objects, organizational units, domains) can easily be explained using a diagram: 

Other diagram examples

FAQ

1. What’s the difference between the free Diagrams App and Diagram Application (Pro)?

The main difference is the maintenance and support model.

The free Diagrams App is a community/contrib extension. Like other contrib extensions, it is maintained by the community, with support usually provided on a best-effort basis.

Diagram Application (Pro) is maintained by XWiki SAS. It includes professional support, regular maintenance, and security fixes. It is also part of the XWiki Pro Apps ecosystem and can be purchased individually or as part of the XWiki Pro package.

2. Can I edit diagrams in full-screen mode?

Diagram Application (Pro) provides a full-screen option while editing, so users can switch from the regular XWiki interface to a wider editing view.

Starting with version 1.24.0, there will also be a new type of diagram that can be launched directly into full-screen edit mode. This is useful when working on larger or more complex diagrams.

3. Which Confluence diagrams can be migrated to XWiki?

Diagram conversion works for draw.io diagrams and Gliffy diagrams.

Gliffy diagram conversion has been supported and used for several years. For other Confluence diagram plug-ins, compatibility needs to be checked case by case, depending on the format and how the diagrams are stored in Confluence.

4. Can migrated diagrams become fully editable in XWiki?

After migration from Confluence, diagrams can be converted so they become editable in XWiki.

Once converted, the diagram can be edited and the changes are reflected in XWiki. The “revert diagram conversion” option remains available, so users can go back if they do not want the diagram to stay editable.

This conversion state is kept visible on purpose, so users can control whether an imported diagram remains editable or not.

5. Can I hide diagram pages from the navigation?

Each diagram is stored as a wiki page, so by default it can appear in the page tree/navigation like other XWiki pages. This is part of how Diagram Application (Pro) integrates diagrams with XWiki’s page model, including permissions and versioning.

A practical workaround is to organize diagram pages under a dedicated hidden or technical space, or place them as child pages where they make sense contextually.

Depending on the wiki configuration, navigation panels can also be customized to hide specific locations or technical pages. This is more of an XWiki navigation configuration topic than a Diagram Application (Pro) setting.

6. When should I use a diagram instead of a regular XWiki page?

Use a diagram when the information is easier to understand visually than as text or tables.

Good examples include processes, workflows, system architecture, organizational structures, dependencies, user journeys, decision trees, network diagrams, UML, BPMN, mockups, and mind maps.

Use regular or structured XWiki pages when the information needs to be queried, filtered, reused as data, or maintained consistently across many pages.

In practice, the best setup is often both: A page as the source of truth, plus a diagram to explain the flow or relationship visually.

7. Can large diagrams affect page performance?

Yes, they can, depending on size, complexity, rendering mode, and where the diagram is displayed.

Large diagrams with many shapes, images, or links can take more time to load or render, especially if they are displayed directly inside frequently visited pages.

Diagram Application (Pro) supports including diagrams in other pages through the Diagram Macro, which includes a cached option. When the cached option is unchecked, users can still zoom and open the diagram in full-screen from the referenced page. So there is a trade-off between interactivity and rendering behavior.

For very large diagrams, it is usually better to keep the diagram on its own page and include it only where needed.

8. Can I add links inside diagrams?

Diagram Application (Pro) supports links inside diagrams, including links to XWiki pages and external documentation.

This is useful when diagrams act as an entry point into more detailed documentation. For example, an architecture diagram can link to technical pages, a process diagram can link to procedures, and an onboarding flow can link to team resources.

Links can also be preserved in exports depending on the export format. For PDF export, SVG-based export can keep clickable text, including links.

9. Should I use diagrams as attachments or create them with Diagram Application (Pro)?

It depends on how you want to use and maintain them.

Using a diagram as an attachment is mostly a static approach. You attach an image or file to a page, and users can view or download it.

Using Diagram Application (Pro) gives you an editable diagram managed inside XWiki. Each diagram is stored in a wiki page, revisions are synchronized with XWiki, and the diagram can be included in other pages using the Diagram Macro.

This makes diagrams easier to maintain as part of living documentation, instead of treating them as isolated files.

Starting with version 1.24.0, there will also be a way to create diagrams as attachments inside a page, giving users more flexibility depending on how they want to organize their content.

10. Can several people edit the same diagram at the same time?

Diagram Application (Pro) supports team collaboration around diagrams, but not simultaneous real-time editing inside the diagram editor.

Diagrams are stored and managed in XWiki, so changes benefit from XWiki’s page history and versioning. This makes it possible to track updates and restore previous versions when needed.

For now, the recommended workflow is for one user to edit the diagram at a time, while the rest of the team collaborates through the surrounding XWiki page using comments, mentions, annotations, and page history.

11. Are diagram changes versioned in XWiki?

Diagram revisions are synchronized with XWiki.

Because each diagram is stored in a wiki page, diagram changes are versioned through XWiki’s standard page history. You can use XWiki versioning to track and restore previous diagram versions, but visual diagram diffing is not documented as a dedicated feature.

12. What happens if someone has access to a page but not to the diagram inside it?

Since each diagram is stored as a wiki page, access rights follow XWiki’s permissions model.

If a page includes a diagram from another source page, the user also needs the appropriate rights to view that diagram source. Otherwise, they may be able to access the documentation page but not see the embedded diagram.

The best practice is to align permissions between the page where the diagram is displayed and the diagram page itself.

13. If I reuse a diagram on several pages, will updates appear everywhere?

When the same diagram is included in multiple pages using the Diagram Macro, those pages reference the same diagram source.

So if you update the diagram source page, the included diagram should reflect the updated version wherever it is reused.

This is one of the advantages of managing diagrams inside XWiki: You can reuse the same diagram in various places without maintaining separate copies manually.

14. Can XWiki search text inside diagrams?

XWiki can index the content of the page. Since diagrams are stored inside that page content, text within diagrams can be searchable.

This is not because Diagram Application (Pro) adds a special diagram-specific search feature. It comes from how XWiki indexes page content.

However, it is better not to rely on search for shapes themselves. Shapes are stored differently by draw.io and may not have a searchable field.

Also, this will not work in the same way with the inline diagrams planned for version 1.24.0.

As a good practice, add a short textual summary near the diagram, plus clear page titles, headings, and tags. This makes diagrams easier to find and improves accessibility.

15. Can XWiki display diagrams stored outside the wiki?

Diagram Application (Pro) supports rendering diagrams hosted elsewhere through the Diagram Macro, which includes a parameter for URLs.

This means that, depending on the setup, a diagram file stored outside XWiki can be rendered in an XWiki page through the macro.

The important distinction is between displaying an externally hosted diagram and managing it fully inside XWiki. If users want XWiki editing, versioning, permissions, and page history for that diagram, then storing it in XWiki is the more complete approach.

External Resources