Formatting

This article covers the formatting choices that apply to both product documentation and courses: text emphasis, code, lists, tables, headings, images, admonitions, file naming, front matter, and placeholders. For voice, phraseology, and organizing principles, see Core Style. For content-type-specific rules, see Documentation Style or Course Style.

Article Naming

Filenames are lowercase kebab-case and match the article’s H1 title. An article titled Using Message Boards has the filename using-message-boards.md. Never title an article Introduction to [Topic] (see also Core Style).

Front Matter

Sort front matter keys alphabetically, along with the values within taxonomy-category-names, but order toc by reading sequence rather than alphabetically. (The rendered page regroups and alphabetizes taxonomy categories on its own, so source order is purely for authoring consistency.)

A typical article’s front matter:

---
showChildrenCards: false
taxonomy-category-names:
  - Liferay PaaS
  - Liferay SaaS
  - Liferay Self-Hosted
toc:
  - ./getting-started.md
  - ./configuring-the-system.md
  - ./managing-users.md
uuid: 12345678-1234-1234-1234-123456789abc
---

Line Breaks

Paragraphs are on a single line; use dynamic word wrap and do not break at 80 columns. Separate paragraphs with two carriage returns.

Bold

Use bold sparingly. The reader’s eye is drawn to bold text, so too much of it dilutes the effect. All headings are bold by rendering, so avoid bolding body text gratuitously.

Use bold in these specific cases:

Field names in forms: Bold the field name followed by a colon when explaining a form.

Name: Enter the user’s name.

Address: Enter the user’s address.

Definition labels: Bold the term being defined (see Definitions).

Sub-section call-outs: When a body section contains multiple distinct labeled sub-items that do not warrant their own heading.

Never end a section with a list of form elements.

Italics

Concept Introductions

When introducing a concept for the first time, italicize the term. Do not italicize subsequent uses.

Liferay DXP is comprised of many OSGi modules. A module is a piece of functionality that can be a self-contained application or an extension to existing functionality.

UI Elements

UI element names — menus, pages, tabs, buttons, fields, and the like — are capitalized as they appear in the interface. Whether to also italicize depends on whether the reader acts on the element in that step.

When telling the reader to click something in the UI, italicize the element name:

Click Save to continue.

When referring to a UI element without a click directive, capitalize it but do not italicize:

After clicking the button, the Configuration page appears.

Combine the two rules to clarify which UI element receives the click:

On the Configuration page, click the Add button.

The element that receives direction is italicized; the surrounding context element is capitalized only.

Code

Offset blocks of code with three backticks and a language identifier:

```java
[Java code here]
```

Surround the following with single backticks so they appear inline as code:

• File names
• Classes
• Database tables
• Variables
• Folders and directories
• CLI commands and flags
• Environment variable names
• Configuration property keys and values
• API endpoint paths
• Port numbers in a technical context (8080)

Definitions

Definitions are paragraphs with the defined term in bold, followed by a colon. They are never bulleted:

Definition: a statement that describes the meaning of a term.

Term: an object, usually a noun, whose meaning must be defined.

A definition must never use the term it is defining.

Lists

Use numbered lists for sequential steps or when the order matters. Use bulleted lists for unordered items. Order bulleted-list items alphabetically when the order does not carry meaning.

When you state the count of items before listing them, use a numbered list:

There are three ways to create a site:

1. Create a site.

2. Create an organization and then a site for that organization.

3. Create a new portal instance and then create a site within it.

When the count is not stated, a bulleted list is fine:

Clicking the button gives you these options:

• View
• Edit
• Delete

Continuing-Sentence Lists

When the lead-in is not a complete sentence on its own and each list item completes it, omit the colon and let the items finish the sentence. This is the right choice when forcing the lead-in to be a complete clause would only add filler (“the following,” “these prerequisites”) to satisfy the colon rule.

Before configuring the ArgoCD domain, you must have

• A deployed CNE environment
• A registered domain (for example, argocd.mydomain.com)

Each item completes the lead-in (“you must have a deployed CNE environment”), so no colon and no filler word are needed.

Numbered List Style

Number every item with 1. (autonumbering). Single- or double-spaced is fine; use blank lines between items when each item contains multiple paragraphs or is more than one line:

1. This is a numbered list. When this paragraph ends, line up the second paragraph with the beginning of the first.

   This is the second paragraph in the first item.

1. This is the second item.

1. This is the third item.

Introducing Steps

Do not use a sentence fragment as a lead-in to steps. A fragment leaves a dangling construction that reads poorly. Either go straight to the first step, or use a brief, complete context sentence.

Bad (fragment lead-in):

## Editing Fields

To edit fields,

1. Step one

Good (steps directly):

## Editing Fields

1. Click the _Edit_ button.

1. Enter a name...

Also good (brief complete sentence before steps):

## Editing Fields

Fields can be edited at any time without affecting published content.

1. Click the _Edit_ button.

1. Enter a name...

Tables

| header 1 | header 2 | header 3 |
| :--- | :--- | :--- |
| cell 1 | cell 2 | cell 3 |

header 1	header 2	header 3
cell 1	cell 2	cell 3

Comparison Tables

When comparing features between items, such as Public and Private Pages, use a table with checkmarks:

| Behavior | Public Pages | Private Pages |
| --- | --- | --- |
| Visible to unauthenticated users | ✔ |  |
| Viewing requires Login and Site Membership |  | ✔ |
| Distinct URL pattern | ✔ | ✔ |

Table Descriptions

A description cell may be a noun phrase or a complete sentence, but a single table must not mix the two — consistency within the table matters more than which style you pick:

• Noun-phrase descriptions take no terminal period (the same convention as list items).
• Complete-sentence descriptions take a period.

If any cell needs a complete sentence — for example, a cell containing more than one sentence — write every cell in that column as a complete sentence.

Noun-phrase descriptions:

Field	Description
Name	Object name shown in the UI
Scope	Availability of entries

Complete-sentence descriptions:

Field	Description
Name	The object name appears in the UI.
Scope	Entries are available within this scope.

Headings

Use headings to create a logical hierarchy that helps readers scan and navigate the article.

• H1: The article title. Exactly one per article. The first heading in the document. Must match the article’s title metadata.
• H2: Major sections within an article. Most articles consist only of H2 sections.
• H3: Subsections when a major section contains two or more distinct sub-topics that each warrant their own heading.
• H4: Use sparingly. Only when an H3 section itself contains distinct sub-categories that cannot be condensed.

Avoid H5 and H6 entirely. If you reach for them, the article needs restructuring or the content belongs in a separate article.

Do not skip levels (for example, jumping from H2 to H4). Screen readers and automated tools depend on a consistent hierarchy.

Variables and Placeholders

Surround placeholders with square brackets to differentiate them from code (which is often surrounded by angle brackets):

The default HSQL database is stored in [Liferay Home]/data.

Images

Storage and Naming

Some images are reused across multiple articles, like icons. There is a shared images folder in the root of each product’s English-language documentation section.

Use one of these prefixes as a naming convention for shared images:

• icon-
• button-
• menu-

Per-article images go in an ./images/ subdirectory next to the article. Name them as sequential numbers: 01.png, 02.png, and so on. When you add, remove, or rearrange screenshots, renumber the sequence so it stays continuous and matches the order the images appear in the article.

Image Capture

Capture icon images at 20×20. Resize screenshots to an appropriate width for the page, generally no more than 800 pixels wide. (For HiDPI display support, capture at 2× resolution and downscale on render where the renderer supports it.)

Alt Text

Every image needs alt text. Alt text is not a label; it is a complete sentence that describes the purpose of the image, not just its appearance.

Bad: The Liferay setup wizard.

Good: The Liferay setup wizard contains fields for selecting your database type and connection.

For complex images that require explanation (diagrams, ERDs, architecture charts), use a two-part approach: provide a brief alt description that identifies the image, and then provide a full textual description in the surrounding article body.

Example: Workflow diagram showing the progression of a content entry from Draft to Approved. See the following text for full details.

For purely decorative images (banners, badges that add no information), use an empty alt attribute (alt=""). Never omit the alt attribute entirely; many screen readers fall back to announcing the file name (for example, banner-v2.png), which is disruptive.

If an image contains text that is not represented in the surrounding article, include the exact text in the alt description.

Image Captions

Markdown does not support native image captions. Alt text serves as the caption: write it as a complete, descriptive sentence that explains what is shown and why it matters. Do not duplicate alt-text content in the surrounding prose.

Highlighting UI Elements in Screenshots

Use box highlighting or numeric annotations to draw the reader’s eye to specific UI elements.

If you use numeric annotations, define what each number represents in the text below the image.

For courses-specific markup conventions (color, screenshot framing standards, the Lexicon Icons Figma source), see Course Style.

Diagrams

Add diagrams to help the reader understand complex concepts: how features relate to each other, how data flows, or anything where a UI screenshot does not capture the relationship. Diagrams are appropriate when:

• Introducing a general concept or methodology.
• Visualizing a backend process, architecture, or data flow that has no UI representation.
• The UI does not clearly distinguish between integrated or overlapping components.
• Visualizing relationships between system components or data structures.
• Comparing multiple features, models, or scenarios side by side.

For a complete list of existing course diagrams, see the Brand portal.

Videos

Upload videos to YouTube, then reference them with the YouTube token:

<iframe allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen frameborder="0" height="315" src="https://www.youtube.com/embed/x7fm_nCZ0sY" title="YouTube video player" width="560"></iframe>

Admonitions

Use admonitions to capture the reader’s attention. They stand out from the main body to call out something important. Do not overuse them — if admonitions occur too frequently, readers skip over them.

The four admonition types each have a specific purpose:

• Note: Background information or context that supplements the main content. The reader can skip it without the steps failing.
• Tip: A shortcut, best practice, or non-obvious approach that improves the reader’s experience.
• Important: Information the reader must have to complete the task correctly. Use when skipping it could cause the steps to fail or produce unexpected results.
• Warning: Information that, if ignored, could cause data loss, security exposure, irreversible changes, or other serious harm.

Usage

!!! tip "[text here goes in title bar]"
    This is a tip. This is a link in a [tip](https://www.liferay.com). Markdown formatting is supported in an admonition.

For full admonition syntax, see the Flexmark Wiki.