# Where to list all macros, UIXPs, etc and missing XClasses in the DocApp

**URL:** <https://forum.xwiki.org/t/where-to-list-all-macros-uixps-etc-and-missing-xclasses-in-the-docapp/18924>\
**Category:** Development\
**Tags:** proposal, documentation\
**Created:** [October 6, 2026, 12:09pm UTC](https://forum.xwiki.org/t/where-to-list-all-macros-uixps-etc-and-missing-xclasses-in-the-docapp/18924 "2026-10-06T12:09:11Z")\
**Posts on this page:** 17\
**Page:** 1

<div class="post-metadata">

**Author:** ![elenicojocariu](https://forum.xwiki.org/letter_avatar_proxy/v4/letter/e/b9e5f3/32.png) [@elenicojocariu](https://forum.xwiki.org/u/elenicojocariu)\
**Post date:** [October 6, 2026, 12:09pm UTC](https://forum.xwiki.org/t/where-to-list-all-macros-uixps-etc-and-missing-xclasses-in-the-docapp/18924/1 "2026-10-06T12:09:11Z")

</div>

Hello everyone 👋,

**Context** : we need a page that gathers all the macros in xwiki. More broadly, we need some “catalogue” pages, that list every doc page carrying a certain type of xobject (rendering macro, UIXP, etc.).

Note: each macro is documented in the topic of the feature it belongs to (e.g.: [https://www.xwiki.org/xwiki/bin/view/documentation/xs/dev/attachments/attachmentselector-macro/](https://www.xwiki.org/xwiki/bin/view/documentation/xs/dev/attachments/attachmentselector-macro/)), but there is no single place to find them all.

## Question 1: What type should a “catalogue” page be?

(I’m not proposing a new type- catalogue, just think the name “catalogue” is intuitive for imagining the page.)

### Option 1: Reference page (my preference)

- It’s a regular documentation page with the `DocumentationClass` attached and type `reference`. The only special thing is the `content` field, a Live Data whose displayed columns depend on the XClass (e.g. `title`, `location`, `description`, `Extension Id` etc).
- It lists everything that exists on the topic (e.g. all macros), which is the definition of a reference page.
- The related section of each page points to its pair for the other target.

#### **Location**

A top-level page under the corresponding target + pinning in the navigation, e.g. `documentation.xs.user.rendering-macros` titled “_All Bundled Macros for Users_”, and `documentation.xs.dev.rendering-macros` titled “_All Bundled Macros for Developers_”. It would be pinned in the navigation probably right after “Base” topic page.

- This is the same approach as the existing all-UIXPs page under the dev guide for previous doc: [https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/ExtensionPoint/](https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/ExtensionPoint/)

### Option 2: Landing page

- A catalogue documents nothing specific. It’s an organizational page that gathers info together.
- Landing pages are created and managed by the doc manager (the type pages- e.g. [How-tos](https://www.xwiki.org/xwiki/bin/view/documentation/xs/user/howto/), the target pages- e.g. [User Documentation](https://www.xwiki.org/xwiki/bin/view/documentation/xs/user/), and the product pages [xs](https://www.xwiki.org/xwiki/bin/view/documentation/xs/) and [extensions](https://www.xwiki.org/xwiki/bin/view/documentation/extensions/)).

#### Location

The catalogue would be listed right after the type landing pages.

To me it makes more sense as a reference page (option 1), since a landing page is structural and this one still carries content about the macros in the “description” column and because it is closer to the definition of a reference page in diataxis. WYT?

## Question 2: What other XCLasses are we missing from the DocApp for documenting pages?

Currently, we have in the Documentation Application `XClasses` for documenting:

- [Rendering macros](https://www.xwiki.org/xwiki/bin/view/documentation/extensions/user/documentation/documentation-xwiki-org/create-documentation-page-rendering-macro/)
- [UIXPs](https://www.xwiki.org/xwiki/bin/view/documentation/extensions/user/documentation/documentation-xwiki-org/create-documentation-page-uixp/)
- For Extensions that are not bundled in XS: [Confluence macros](https://www.xwiki.org/xwiki/bin/view/documentation/extensions/user/documentation/documentation-xwiki-org/confluence/create-documentation-page-confluence-macro/) and [Confluence plugins](https://www.xwiki.org/xwiki/bin/view/documentation/extensions/user/documentation/documentation-xwiki-org/confluence/create-documentation-page-confluence-plugin/))

=\>

- I propose to have a `XClass` for documenting **Icons** (I’m going to create another proposal for its `xproperties`)
- Have an `XClass` for **Troubleshooting** pages (I’ve been consistently using a “Cause” / “Solution” heading structure on troubleshooting pages, but they are currently typed as explanation e.g.: [File path too long on Windows](https://www.xwiki.org/xwiki/bin/view/documentation/xs/admin/installation/troubleshooting/file-path-long-windows-unzipping/), [Multiple instances in the container](https://www.xwiki.org/xwiki/bin/view/documentation/xs/admin/installation/troubleshooting/multiple-instances-container/), [Unable to create native thread on Debian](https://www.xwiki.org/xwiki/bin/view/documentation/xs/admin/installation/methods/install-xwiki-war/configure-servlet-container/configure-tomcat/troubleshooting/unable-create-native-thread-errors-debian-systems/)).
- What else?

Thanks!

---

<div class="post-metadata">

**Author:** ![vmassol](https://forum.xwiki.org/user_avatar/forum.xwiki.org/vmassol/32/6_2.png) [@vmassol](https://forum.xwiki.org/u/vmassol)\
**Post date:** [October 6, 2026, 12:21pm UTC](https://forum.xwiki.org/t/where-to-list-all-macros-uixps-etc-and-missing-xclasses-in-the-docapp/18924/2 "2026-10-06T12:21:37Z")

</div>

> [@elenicojocariu](#):
>
> Question 1: What type should a “catalogue” page be?

+1 for a doc Reference type page.

> [@elenicojocariu](#):
>
> A top-level page under the corresponding target + pinning in the navigation, e.g. `documentation.xs.user.rendering-macros` titled “_All Bundled Macros for Users_”, and `documentation.xs.dev.rendering-macros` titled “_All Bundled Macros for Developers_”. It would be pinned in the navigation probably right after “Base” topic page.

As a rule, I think I’d simply propose to use a reference page under the explanation page that explains the concept in question. For example, we will document somewhere what is a (Rendering) Macro in XWiki, and that will be an explanation page. Then we could have a reference page below it (i.e. nested) that would list all macros. Same for UIXPs, etc.

The separation by target is more tricky and depends on the topic. For example for UIXP, they’re all for developers. For macros, indeed, we can have macros for users and macros for developers. The pages should be cross-linked probably (maybe using the Related section).

WDYT?

> [@elenicojocariu](#):
>
> Question 2: What other XCLasses are we missing from the DocApp for documenting pages?

For these, I think we’ll find them as we progress. The troubleshooting type of pages is a good candidate indeed. For icons, I’m not sure what you mean. What does it mean to document an “icon”? IMO Icons should be grouped by Icon Set and have one page per icon set (we won’t have many though, since we have only 2 icon sets we support ATM).

Thanks!

---

<div class="post-metadata">

**Author:** ![elenicojocariu](https://forum.xwiki.org/letter_avatar_proxy/v4/letter/e/b9e5f3/32.png) [@elenicojocariu](https://forum.xwiki.org/u/elenicojocariu)\
**Post date:** [October 6, 2026, 12:49pm UTC](https://forum.xwiki.org/t/where-to-list-all-macros-uixps-etc-and-missing-xclasses-in-the-docapp/18924/3 "2026-10-06T12:49:39Z")

</div>

> [@vmassol](#):
>
> As a rule, I think I’d simply propose to use a reference page under the explanation page that explains the concept in question. For example, we will document somewhere what is a (Rendering) Macro in XWiki, and that will be an explanation page. Then we could have a reference page below it (i.e. nested) that would list all macros. Same for UIXPs, etc.

Thx for the feedback! Sounds good.

> [@vmassol](#):
>
> The pages should be cross-linked probably (maybe using the Related section).

→ I agree. This is already proposed:

> [@elenicojocariu](#):
>
> - The related section of each page points to its pair for the other target.

> [@vmassol](#):
>
> For icons, I’m not sure what you mean. What does it mean to document an “icon”? IMO Icons should be grouped by Icon Set and have one page per icon set

I’m referring to the icon pages that already exist in the old documentation, under [Front-end Resources \> Icons](https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/FrontendResources/Icons/), where each page (e.g. [backward](https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/FrontendResources/Icons/backward)) maps an XWiki IconSet name to its name in each icon theme (Silk, Font Awesome,..) using the `IconMappingClass`. =\> So probably we’ll need to move and improve to the docapp the IconMappingClass.

Thanks!

---

<div class="post-metadata">

**Author:** ![elenicojocariu](https://forum.xwiki.org/letter_avatar_proxy/v4/letter/e/b9e5f3/32.png) [@elenicojocariu](https://forum.xwiki.org/u/elenicojocariu)\
**Post date:** [October 6, 2026, 12:53pm UTC](https://forum.xwiki.org/t/where-to-list-all-macros-uixps-etc-and-missing-xclasses-in-the-docapp/18924/4 "2026-10-06T12:53:17Z")

</div>

**Another idea** : if we end up with more of these “catalogue” pages, we could add a new panel called “Indexes” (name open to suggestions) and place it under the target panel in [xwiki.org](http://xwiki.org). Each product and target would have its own hierarchy, depending on what exists there. For example:

- `xs.user` \> **Indexes** panel would list: Icons, all bundled macros for users

- `xs.dev` \> **Indexes** : all UIXPs, all troubleshooting pages

This way we provide more visibility to such pages. WDYT?

( Just realized this would be an index of indexes :)) )

---

<div class="post-metadata">

**Author:** ![vmassol](https://forum.xwiki.org/user_avatar/forum.xwiki.org/vmassol/32/6_2.png) [@vmassol](https://forum.xwiki.org/u/vmassol)\
**Post date:** [October 6, 2026, 12:58pm UTC](https://forum.xwiki.org/t/where-to-list-all-macros-uixps-etc-and-missing-xclasses-in-the-docapp/18924/5 "2026-10-06T12:58:26Z")

</div>

> [@elenicojocariu](#):
>
> I’m referring to the icon pages that already exist in the old documentation, under [Front-end Resources \> Icons](https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/FrontendResources/Icons/), where each page (e.g. [backward](https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/FrontendResources/Icons/backward)) maps an XWiki IconSet name to its name in each icon theme (Silk, Font Awesome,..) using the `IconMappingClass`. =\> So probably we’ll need to move and improve to the docapp the IconMappingClass.

ok I didn’t know about this xclass. From what I see the goal is not so much to have one page per icon (since we have no links to these pages), but more to have a LD listing all of them. I feel that it might look odd in the top level LDs to list all those icons as pages.

One solution is to consider these icon pages as internal pages and without them being doc pages, and they’d just be used by the LD in the doc page for the Icon Set. WDYT?

cc @CharpentierLucas

---

<div class="post-metadata">

**Author:** ![vmassol](https://forum.xwiki.org/user_avatar/forum.xwiki.org/vmassol/32/6_2.png) [@vmassol](https://forum.xwiki.org/u/vmassol)\
**Post date:** [October 6, 2026, 1:04pm UTC](https://forum.xwiki.org/t/where-to-list-all-macros-uixps-etc-and-missing-xclasses-in-the-docapp/18924/6 "2026-10-06T13:04:30Z")

</div>

> [@elenicojocariu](#):
>
> This way we provide more visibility to such pages. WDYT?

Sounds good. We would need to test how it looks visually. It may feel a bit weird to have this Index panel before the topics since you need to understand the topics before being interesting in these indexes. Maybe they could be below the topics instead.

Let’s see what others think.

Thx

---

<div class="post-metadata">

**Author:** ![CharpentierLucas](https://forum.xwiki.org/user_avatar/forum.xwiki.org/charpentierlucas/32/4830_2.png) [@CharpentierLucas](https://forum.xwiki.org/u/CharpentierLucas)\
**Post date:** [October 7, 2026, 8:06am UTC](https://forum.xwiki.org/t/where-to-list-all-macros-uixps-etc-and-missing-xclasses-in-the-docapp/18924/7 "2026-10-07T08:06:58Z")

</div>

+1 for keeping them as internal pages. I created them mostly to contain the info of one icon only in a maintainable way. I don’t think the info about a single icon is worth its own reference page.

Thank you!

---

<div class="post-metadata">

**Author:** ![elenicojocariu](https://forum.xwiki.org/letter_avatar_proxy/v4/letter/e/b9e5f3/32.png) [@elenicojocariu](https://forum.xwiki.org/u/elenicojocariu)\
**Post date:** [October 7, 2026, 11:40am UTC](https://forum.xwiki.org/t/where-to-list-all-macros-uixps-etc-and-missing-xclasses-in-the-docapp/18924/8 "2026-10-07T11:40:26Z")

</div>

> [@vmassol](#):
>
> One solution is to consider these icon pages as internal pages and without them being doc pages,

> [@CharpentierLucas](#):
>
> +1 for keeping them as internal pages.

By “internal” pages do you mean to have them hidden, but still move them in the new documentation, or to have them created outside the “Documentation” (or “documentation”) space? (If we don’t need them in the doc I wouldn’t move them, maybe they could be the only pages remaining under the previous doc, marked as hidden). WYT?

Anyway, I agree with having in the new doc just a page that displays the mapping in a LD.  
Thanks!

---

<div class="post-metadata">

**Author:** ![CharpentierLucas](https://forum.xwiki.org/user_avatar/forum.xwiki.org/charpentierlucas/32/4830_2.png) [@CharpentierLucas](https://forum.xwiki.org/u/CharpentierLucas)\
**Post date:** [October 7, 2026, 12:25pm UTC](https://forum.xwiki.org/t/where-to-list-all-macros-uixps-etc-and-missing-xclasses-in-the-docapp/18924/9 "2026-10-07T12:25:56Z")

</div>

> [@elenicojocariu](#):
>
> By “internal” pages do you mean to have them hidden, but still move them in the new documentation, or to have them created outside the “Documentation” (or “documentation”) space? (If we don’t need them in the doc I wouldn’t move them, maybe they could be the only pages remaining under the previous doc, marked as hidden). WYT?

Yes I meant keeping them as hidden. If that’s alright for now, we can leave them where they are. We’ll just have to remember to move them when eventually we decide to retire completely [the previous doc devguide](http://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide).

---

<div class="post-metadata">

**Author:** ![elenicojocariu](https://forum.xwiki.org/letter_avatar_proxy/v4/letter/e/b9e5f3/32.png) [@elenicojocariu](https://forum.xwiki.org/u/elenicojocariu)\
**Post date:** [October 7, 2026, 1:42pm UTC](https://forum.xwiki.org/t/where-to-list-all-macros-uixps-etc-and-missing-xclasses-in-the-docapp/18924/10 "2026-10-07T13:42:05Z")

</div>

For now, I have created:

- [https://www.xwiki.org/xwiki/bin/view/documentation/xs/user/rendering-macros/](https://www.xwiki.org/xwiki/bin/view/documentation/xs/user/rendering-macros/)

- [https://www.xwiki.org/xwiki/bin/view/documentation/xs/dev/rendering-macros/](https://www.xwiki.org/xwiki/bin/view/documentation/xs/dev/rendering-macros/)

- OP issue for XClass for troubleshooting page: [Add a Documentation XClass for troubleshooting pages](https://op.xwiki.org/projects/DA/work_packages/DA-97/activity).

---

<div class="post-metadata">

**Author:** ![vmassol](https://forum.xwiki.org/user_avatar/forum.xwiki.org/vmassol/32/6_2.png) [@vmassol](https://forum.xwiki.org/u/vmassol)\
**Post date:** [October 7, 2026, 2:14pm UTC](https://forum.xwiki.org/t/where-to-list-all-macros-uixps-etc-and-missing-xclasses-in-the-docapp/18924/11 "2026-10-07T14:14:35Z")

</div>

Thx Eleni!

> [@elenicojocariu](#):
>
> - [https://www.xwiki.org/xwiki/bin/view/documentation/xs/user/rendering-macros/](https://www.xwiki.org/xwiki/bin/view/documentation/xs/user/rendering-macros/)

We need to work a bit on [https://www.xwiki.org/xwiki/bin/view/documentation/xs/user/rendering-macros/](https://www.xwiki.org/xwiki/bin/view/documentation/xs/user/rendering-macros/) :

- It’s not very user friendly (showing “code”)
- It’s missing a lot of things about Rendering and Rendering Macros. In short we need to migrate the docs from [rendering.xwiki.org](http://rendering.xwiki.org) to the main wiki.
- It’s pointing to BlockNote instead of our WYSWIYG editor
- I think it’s not in the right location so we’ll need to move it, which is always a bit painful (we need a Rendering top level probably)

> [@elenicojocariu](#):
>
> - [https://www.xwiki.org/xwiki/bin/view/documentation/xs/user/rendering-macros/bundled-rendering-macros/](https://www.xwiki.org/xwiki/bin/view/documentation/xs/user/rendering-macros/bundled-rendering-macros/)

Looks good. Good idea with the filtering to have a single table.

Thx

---

<div class="post-metadata">

**Author:** ![vmassol](https://forum.xwiki.org/user_avatar/forum.xwiki.org/vmassol/32/6_2.png) [@vmassol](https://forum.xwiki.org/u/vmassol)\
**Post date:** [October 7, 2026, 7:25pm UTC](https://forum.xwiki.org/t/where-to-list-all-macros-uixps-etc-and-missing-xclasses-in-the-docapp/18924/12 "2026-10-07T19:25:09Z")

</div>

Related to this topic: [Documenting REST APIs with dedicated XClasses in the Documentation Application](https://forum.xwiki.org/t/documenting-rest-apis-with-dedicated-xclasses-in-the-documentation-application/18932)

---

<div class="post-metadata">

**Author:** ![elenicojocariu](https://forum.xwiki.org/letter_avatar_proxy/v4/letter/e/b9e5f3/32.png) [@elenicojocariu](https://forum.xwiki.org/u/elenicojocariu)\
**Post date:** [October 9, 2026, 8:59am UTC](https://forum.xwiki.org/t/where-to-list-all-macros-uixps-etc-and-missing-xclasses-in-the-docapp/18924/13 "2026-10-09T08:59:20Z")

</div>

I have updated the page a bit: [https://www.xwiki.org/xwiki/bin/view/documentation/xs/user/rendering-macros/](https://www.xwiki.org/xwiki/bin/view/documentation/xs/user/rendering-macros/). It currently shows a false violation because it contains in the title and name the `rendering` word which here is not a verb.

Yes, it is agreed in some forum post already that the pages from [rendering.xwiki.org](http://rendering.xwiki.org) will be moved to the new doc. I’ll need to find it. However, I don’t think there are many user pages in it.

> [@vmassol](#):
>
> - I think it’s not in the right location so we’ll need to move it, which is always a bit painful (we need a Rendering top level probably)

→ for users I’m not sure we do (yet). For developers most probably indeed. Thanks!

---

<div class="post-metadata">

**Author:** ![vmassol](https://forum.xwiki.org/user_avatar/forum.xwiki.org/vmassol/32/6_2.png) [@vmassol](https://forum.xwiki.org/u/vmassol)\
**Post date:** [October 9, 2026, 10:39am UTC](https://forum.xwiki.org/t/where-to-list-all-macros-uixps-etc-and-missing-xclasses-in-the-docapp/18924/14 "2026-10-09T10:39:13Z")

</div>

> [@elenicojocariu](#):
>
> It currently shows a false violation because it contains in the title and name the `rendering` word which here is not a verb.

Fixed in [Making sure you're not a bot!](https://op.xwiki.org/projects/DA/work_packages/DA-104/activity) .

---

<div class="post-metadata">

**Author:** ![elenicojocariu](https://forum.xwiki.org/letter_avatar_proxy/v4/letter/e/b9e5f3/32.png) [@elenicojocariu](https://forum.xwiki.org/u/elenicojocariu)\
**Post date:** [October 22, 2026, 4:02pm UTC](https://forum.xwiki.org/t/where-to-list-all-macros-uixps-etc-and-missing-xclasses-in-the-docapp/18924/15 "2026-10-22T16:02:13Z")

</div>

Thanks for the feedback! Here is what we agreed on:

- Use a **Reference page** (a Live Data listing everything on the topic), located under the explanation page that describes the concept.
- Created catalogue pages:
  - [Bundled rendering macros (dev)](https://www.xwiki.org/xwiki/bin/view/documentation/xs/dev/rendering-macros/bundled-rendering-macros/)
  - [Bundled rendering macros (user)](https://www.xwiki.org/xwiki/bin/view/documentation/xs/user/rendering-macros/bundled-rendering-macros/)
  - [Bundled UI extension points (dev)](https://www.xwiki.org/xwiki/bin/view/documentation/xs/dev/ui-extension-points/bundled/)
  - [UI extension points of non-bundled extensions (dev)](https://www.xwiki.org/xwiki/bin/view/documentation/extensions/dev/ui-extension-points/)

- Similar catalogue pages still need to be created for other non-bundled extension content, such as [Confluence macros](https://www.xwiki.org/xwiki/bin/view/documentation/extensions/user/documentation/documentation-xwiki-org/confluence/create-documentation-page-confluence-macro/) and [Confluence plugins](https://www.xwiki.org/xwiki/bin/view/documentation/extensions/user/documentation/documentation-xwiki-org/confluence/create-documentation-page-confluence-plugin/).
- Icons: no per-icon documentation pages. The existing icon pages stay hidden, and the new doc gets a single page displaying the mapping in a Live Data.
- An improvement was opened for an XClass for troubleshooting pages: [DA-97](https://op.xwiki.org/projects/DA/work_packages/DA-97/activity).

**Still open:** an index page that lists all the catalogue pages and would sit in the navigation panel. This will be discussed in another thread / tested first.

Thanks!

---

<div class="post-metadata">

**Author:** ![vmassol](https://forum.xwiki.org/user_avatar/forum.xwiki.org/vmassol/32/6_2.png) [@vmassol](https://forum.xwiki.org/u/vmassol)\
**Post date:** [October 23, 2026, 7:26am UTC](https://forum.xwiki.org/t/where-to-list-all-macros-uixps-etc-and-missing-xclasses-in-the-docapp/18924/16 "2026-10-23T07:26:37Z")

</div>

Sounds good. Thx

> [@elenicojocariu](#):
>
> - Bundled rendering macros (dev)

Note that the location at [https://www.xwiki.org/xwiki/bin/view/documentation/xs/dev/rendering-macros/](https://www.xwiki.org/xwiki/bin/view/documentation/xs/dev/rendering-macros/) is still not good (see the discussion we had on `#xwiki`) and will require renaming all pages, since we’ll need to have a top level Rendering entry and move Rendering Macros under it. So the sooner the better to avoid either breaking readers or having to create redirects.

Thx

---

<div class="post-metadata">

**Author:** ![vmassol](https://forum.xwiki.org/user_avatar/forum.xwiki.org/vmassol/32/6_2.png) [@vmassol](https://forum.xwiki.org/u/vmassol)\
**Post date:** [October 23, 2026, 7:29am UTC](https://forum.xwiki.org/t/where-to-list-all-macros-uixps-etc-and-missing-xclasses-in-the-docapp/18924/17 "2026-10-23T07:29:35Z")

</div>

Note that we’re missing macros from Extensions, I think we need to add them as readers need to find them. Same for the other types. We probably need a column to indicate if each row is bundled in XS or comes from an Extension.
