Skip to main content

Basic text elements

This topic covers how to structure the page, write procedures, add notices, and link between topics.

Use Markdown by default

If possible, use native Markdown content structures. Use HTML only when the content type requires it (tables with rich cells, sized figures).

Live preview

For a live preview, start a local server, and check the output in your browser.

Applying the right Markdown structures​

If you're new to Markdown, here's a short reference of the most common text structures.

Reader needRecommended structure
Procedure (ordered steps)Numbered list (1. 2. 3.)
Concept or optionsShort paragraphs + bullets
Warning / tip / note:::warning / :::tip / :::note
Cross-referenceDocs URL or ./file.mdx link

For more information on linking, see Linking between topics.
For code, tabs, and tables, see Code and data.
For images and figures, see Graphics.

Adding headings​

  1. Keep one H1.
    By default, it should match the topic title from the front matter.
  2. Use H2 (##) for major sections.
    This template’s On this page list shows H2 only.
  3. Use H3 (###) for sub-steps or subtopics under an H2.

Linking to a heading​

By default, the heading becomes the anchor. For example, the link to the Example outline section below is basic-text-elements#example-outline.

If you want a custom anchor, you can define it like this:

## Installing the client {/* #client-installation */}

The resulting link is basic-text-elements#client-installation.

Example outline​

# Configuring notifications

## Before you start
## Turning on email alerts
## Choosing a digest schedule
## Troubleshooting missing mail

Creating procedures​

Use numbered lists for anything the reader must do in order. Nest sub-steps with indented numbers or bullets.

List indentation

If possible, use the native Markdown content structures. Use HTML only when the content type requires it (tables with rich cells, sized figures).

Standard procedure​

  1. Open Settings > Notifications.
  2. Select Email alerts.
    Optionally, you can also select SMS alerts.
  3. Select a frequency:
    1. Immediate for every event
    2. Daily digest for a summary
  4. Select Save.

Procedure with a nested tip​

Indent the admonition under the step (use a 3-space indent, and optionally, a blank line after the step text):

  1. Review the sidebar labels before you publish.

    Keep labels short

    Long category names wrap awkwardly on smaller screens.

  2. Continue with the next checklist item after the notice.

Mixed list​

  1. Open the docs folder.
  2. Create or edit an .mdx file:
    • Use headings for structure.
    • Keep one idea per paragraph.
    • Prefer short lists for steps.
  3. Save and confirm the page updates.

Creating notices​

Select the notice type by severity:

TypeUse case
:::noteExtra context that is useful but not blocking
:::tipA shortcut or best practice
:::infoNeutral background the reader should know
:::warningA mistake that causes pain or rework
:::dangerData loss, security, or irreversible action

You can add a custom title:

Name the outcome

Notices accept an optional [title] after the type.

Linking between topics​

Prefer docs URL paths so links stay clear in review:

See [Creating topics](/docs/template-description/create-content/creating-topics).

Same-folder relative links also work (include .mdx):

See [Creating topics](./creating-topics.mdx).

Result: See Creating topics.

Do not use bare paths like /creating-topics — they are not doc routes on this site.

On this page: