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 need	Recommended structure
Procedure (ordered steps)	Numbered list (1. 2. 3.)
Heading-style numbered list	HeadingList / HeadingItem
Concept or options	Short paragraphs + bullets
Warning / tip / note	:::warning / :::tip / :::note
Cross-reference	Docs 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.

Heading-style numbered list

For highlevel overviews that need large numbers and a heading-style line per item, use HeadingList instead of raw HTML. Body text under each title stays normal Markdown.

1. Import the components at the top of the topic, after the front matter:

import HeadingList, {
  HeadingItem,
} from '@site/src/components/HeadingList';

@site means the project root, so this loads src/components/HeadingList.

2. Add the list in the body. Keep blank lines around each HeadingItem so Markdown in the body parses correctly:

<HeadingList>

<HeadingItem title="Choose the primary colour.">

Set `--ifm-color-primary` in `src/css/custom.css`.

</HeadingItem>

<HeadingItem title="Check the home page.">

Refresh the site and confirm the hero banner uses the new colour.

</HeadingItem>

</HeadingList>

Result:

1. Choose the primary colour.

   Set --ifm-color-primary in src/css/custom.css.

2. Check the home page.

   Refresh the site and confirm the hero banner uses the new colour.

note

Titles are visual only. They do not appear in On this page.

Creating notices

Select the notice type by severity:

Type	Use case
:::note	Extra context that is useful but not blocking
:::tip	A shortcut or best practice
:::info	Neutral background the reader should know
:::warning	A mistake that causes pain or rework
:::danger	Data 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.

Related content

• Creating topics
• Code and data
• Graphics
• Sidebar and table of contents