developers.home-assistant/docs/documenting/lorem-ipsum.md

title
Documentation structure and example text

This page shows examples of the available documentation features (such as inline icons, text box, links to related topics, and glossary entries). It also shows the documentation structure.

Use this template together with the following documentation:

• The integration documentation template on under /_integrations/_integration_docs_template.md.
• Documentation standard.
• The documentation rules of the Integration Quality Scale.

Inline text elements

This section shows elements you can use within your text.

My links

To indicate a location in the UI, you can use a My link. If the reader selects that link, that page opens in their installation. For example: "Go to {% my integrations title="**Settings** > **Devices & services**" %} and select your integration."

Screenshot showing the styling of my links:

Here are a few examples:

- {% my areas title="**Settings** > **Areas, labels & zones**" %}
- {% my automations title="**Settings** > **Automations & scenes**" %}
- {% my backup title="**Settings** > **System** > **Backups**" %}
- {% my general title="**Settings** > **System** > **General**" %}
- {% my logs title="**Settings** > **System** > **Logs**" %}
- {% my network title="**Settings** > **System** > **Network**" %}
- {% my profile title="**User profile**" %}

To identify a My link, in Home Assistant, open the page of interest and press the m key.

Formatting

• Use bold when referring to UI strings: Settings, Areas, labels & zones
• Use backtick when referring to file paths, file names, variable names, or a text that you enter in a field: the /boot/config.txt file, the this variable, enter /newbot.

Glossary term reference

Some Home Assistant terms and concepts are explained in a Glossary. If you add a reference to the definition of such a term, the term definition is shown as a tooltip.

Screenshot showing the styling of a glossary term tooltip:

For example:

{% term integration %}
{% term entity %}
{% term "configuration.yaml" %}
{% term "Home Assistant Operating System" %}

You can find the full list of glossary terms on the Glossary page. To learn more about glossary terms, refer to the developer documentation on glossary.

Acronyms and abbreviations

If possible, try to avoid using abbreviations and acronyms.

If you want to use an acronym or abbreviation, you can add an abbreviation tag to show the full term as a tooltip.

Screenshot showing the styling of an abbreviation tooltip:

Here a few examples:

<abbr title="Audio & video">A/V</abbr>,
<abbr title="current transformers">CT</abbr>,
<abbr title="Dutch smart meter requirement">DSMR</abbr>,
<abbr title="embedded MultiMediaCard">eMMC</abbr>,
<abbr title="flash video">FLV</abbr>,
<abbr title="Large Language Models">LLMs</abbr>,
<abbr title="Model Context Protocol">MCP</abbr>,
<abbr title="pan, tilt, and zoom">PTZ</abbr>,
<abbr title="real-time messaging protocol">RTMP</abbr>,
<abbr title="real-time streaming protocol">RTSP</abbr>,
or <abbr title="USB-On-The-Go">USB-OTG</abbr>.

Inline icons

To refer to an icon in the UI, you can use icons from the Iconify library.

Screenshot showing some inline icons:

Here are some examples:

- Three dots menu: {% icon "mdi:dots-vertical" %}
- Hamburger menu: {% icon "mdi:menu" %}
- Edit: {% icon "mdi:edit" %}
- Revert {% icon "mdi:restore" %}
- Eye: {% icon "mdi:eye" %}
- Trash: {% icon "mdi:trash" %}
- Cog: {% icon "mdi:cog" %}
- Cog outline: {% icon "mdi:cog-outline" %}
- Drag: {% icon "mdi:drag" %}
- Move-cursor: {% icon "mdi:cursor-move" %}
- Arrow left: {% icon "mdi:arrow-left-bold" %}
- Arrow right: {% icon "mdi:arrow-right-bold" %}
- Checkbox list: {% icon "mdi:order-checkbox-ascending" %}
- Upload network: {% icon "mdi:upload-network" %}
- Security network: {% icon "mdi:security-network" %}
- Routes: {% icon "mdi:routes" %}

Collapsible text block

Use a details block to make a text block collapsible:

Screenshot showing a collapsible text block:

Example:

{% details "Generate Client ID and Client Secret" %}

1. Your Fitbit account must be registered as a Developer account at the [Fitbit Developer Portal](https://dev.fitbit.com), and have a verified email address.
2. Visit the [fitbit developer page](https://dev.fitbit.com/apps/new) to register an application.
3. Enter an **Application Name** of your choosing, for example **Home Assistant**.
4. ...
{% enddetails %}

Text boxes

Screenshot showing text boxes:

Example:

{% note %}
You can use a note to highlight a section.
{% endnote %}

{% important %}
You can use "important" to highlight a section that you feel is very important.
{% endimportant %}

Reusable text

For some topics, there are predefined text elements that you can reuse.

Configuration

Screenshot showing the predefined configuration text block:

To use this element, add the following line:

{% include integrations/config_flow.md %}

Images

You can use an image to illustrate a step:

Markdown syntax to add an image:

1. To adjust the light temperature and brightness, move the sliders:
    ![Screenshot of tile cards with features](/images/dashboards/features/screenshot-tile-feature-grid.png)
2. Then do this ...

You can add an image with caption:

HTML syntax to add an image, example:

<p class='img'><img src='/images/dashboards/features/screenshot-tile-feature-grid.png' alt="Screenshot of tile cards with features.">
Screenshot of tile cards with features.
</p>

Videos

Use the following syntax to reference a video from Youtube. Use videoStartAt to have it start playback at a specific time in the video:

<lite-youtube videoid="ZgoaoTpIhm8" videoStartAt="3907" videotitle="Introducing the Home Assistant Voice Preview Edition - Voice: Chapter 8"></lite-youtube>

Document structure with example text

This section outlines the document structure. To view example text, refer to the integration documentation template in the homeassistant.io repository under /_integrations/_integration_docs_template.md. The example text includes some reusable text blocks (includes) such as include integrations/config_flow.md and styling elements such as configuration_basic.

The examples are taken from the Integration Quality Scale.

Basic structure

• Introduction
  • Use case
• Supported/unsupported devices
• Prerequisites
• Configuration
• Configuration options
• Supported functionality
• Actions
• Examples
• Data updates
• Known limitations
• Troubleshooting
• Community notes
• Removing the integration