Page Titles and Page Names
Last modified by Eleni Cojocariu on 2026/04/07 10:30
Whenever you create or edit a documentation page, it is important to follow a consistent style. The rules below provide guidance on structure and terminology for page names and titles.
- Page Titles should follow closely the Page Name.
- All Page Titles and Page Names must be meaningful and understandable out of context, such that readers should be able to understand what a page is about. This is important because pages are often accessed through search results, bookmarks, links, where context is missing.
- Page Titles and Names must not include the type of the page ("How to", "Explanation", etc.). These are considered reserved terms, since the page type is already conveyed though the content, structure, badge, context. Including them in titles or names creates redundancy.
Diataxis Reflected in Page Title and Page Content
Diataxis is reflected not only in the way the documentation is organized, but also in its style. The type of the documentation page influences the style rules, make sure that page titles and content follow the conventions for that type.
| How-to | Tutorial | Reference | Explanation | |
|---|---|---|---|---|
| Page titles | Titles must start with a verb (e.g. "Select", "Apply", "Set", etc) |
|
|
|
| Page content |
| Any step in a Tutorial must start with a verb and each step is an item of a numbered list. Short example sentences at any step are allowed to illustrate what exactly needs to be done. |
| Explanations-type pages are describing concepts, limitations, consequences, most of the time answering the question "Why". |
| Examples | "Edit a Page", "Build an Application" (and not "Editing a Page", "Building an Application"). More examples on How-tos for Users. | "Build a FAQ Application". | "All Wiki Pages", "Common Edit Actions", "Realtime Edit Actions". More examples on References for Users. | "Simple and Advanced User", "Conflict Resolution". More examples on Explanations for Users. |
- When you want to add a disambiguation to a page title, you can do so by adding a qualifying phrase in parentheses `()` It's not necessary to add it to the page name. (For example:
All the Pages on the Wiki (for Administrators), All the Pages on the Wiki (for Users), Use Colibri ColorTheme Variables (Deprecated)).
Page Names
Any new page created on xwiki.org, as well as any extension page that has been completely refactored into the new location of Documentation pages (where the only remaining content is a link to the extension documentation and the extension is renamed), must follow the rules for naming:
- Use the naming strategy for kebab-case when naming pages.
- Until when XWiki.org is upgraded to XWiki 18.1.0+ Remove stop words manually. Do not include common stop words such as "a", "the", "on", "when", "while" etc. See full list of stop words.
- Page names should follow page titles as closely as possible while still respecting the rules above.
- Avoid repetition in URL paths.
- Do not repeat the same word (or variations of it) in both parent and child page names. Instead, rely on the parent path to provide context. For example,
../wiki-editor-toolbar/wiki-editor-toolbar-supportrepeats "wiki-editor-toolbar", so the correct name is../wiki-editor-toolbar/support.
- Do not repeat the same word (or variations of it) in both parent and child page names. Instead, rely on the parent path to provide context. For example,
