| name | home-assistant-markdown-liquid-style |
| description | Use this when editing Home Assistant Markdown, Liquid, internal links, images, videos, glossary terms, My links, text boxes, or other website syntax. |
Home Assistant Markdown and Liquid style
The Home Assistant website is built with Jekyll. Pages are written in Markdown with some Liquid templating. Prefer Markdown over HTML where possible.
For linting, the project uses remark and textlint.
Website data files
The following data files are downloaded or generated by the Rakefile during the build process. Do not flag these as missing, search for them, or suggest guards for their absence:
site.data.analytics_datasite.data.alerts_datasite.data.version_datasite.data.language_scoressite.data.codeowners
Markdown
- Use GitHub Flavored Markdown.
- Use Markdown for writing content. Avoid HTML where possible.
- Use lists instead of tables where possible.
- When using a fenced code block, specify the language for syntax highlighting.
- Content inside fenced code blocks must not exceed 80 characters per line.
- Use ATX-style headings with
#.
- Ensure heading increments are correct and do not skip levels. The title in the front matter is the first-level heading, so page content should start at heading level 2.
- Use
- for unordered lists.
- For ordered lists, use increasing numbers.
- Use
_ for italic text and ** for bold text.
- Use backticks when referring to file paths, file names, variable names, or text entered in a field.
Links
- When linking to pages in the same repository, use absolute links and ignore the
source directory.
- Ignore the leading underscore in the first directory. For example, to link to
source/_integrations/date.markdown, use /integrations/date/.
- Use
/ instead of file extensions like .markdown, .md, or .mdx.
- Do not use affiliate or tracking links.
- Do not use bare URLs in body text.
My links
Use My links to open a page in the reader's own Home Assistant installation when that helps them follow a UI path.
Example:
Go to {% my integrations title="**Settings** > **Devices & services**" %} and select your integration.
Common My links:
- {% 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**" %}
Glossary term references
Use glossary term tooltips where they help explain Home Assistant-specific terms.
Syntax: {% term <term> [<text>] %}
Examples:
{% term integration %}
{% term entity %}
{% term "configuration.yaml" %}
{% term "Home Assistant Operating System" %}
Terms can be either their term or one of their aliases. See source/_data/glossary.yml for all terms and aliases. If a term is missing from the glossary, add or improve it in source/_data/glossary.yml.
Acronyms and abbreviations
Avoid abbreviations and acronyms when possible. If you need one, add an abbreviation tag to show the full term as a tooltip.
<abbr title="Audio & video">A/V</abbr>
<abbr title="Model Context Protocol">MCP</abbr>
<abbr title="real-time streaming protocol">RTSP</abbr>
Inline icons
To refer to an icon in the UI, use icons from the Iconify library.
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" %}
- Drag: {% icon "mdi:drag" %}
Collapsible text blocks
Use the Home Assistant Liquid details block. Do not use the HTML5 variant.
{% 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**.
{% enddetails %}
Text boxes
Use text boxes to highlight important information, but do not overuse them.
{% tip %}
Use a tip to feature a recommendation.
{% endtip %}
{% note %}
Use a note to highlight helpful information.
{% endnote %}
{% important %}
Use important for information readers should not miss.
{% endimportant %}
{% caution %}
Use a caution box to advise against actions that may cause data loss, unintended behavior, or other consequences that are difficult to reverse.
{% endcaution %}
{% warning %}
Use a warning box to alert readers to risks that could compromise the security or integrity of their system, or cause physical harm.
{% endwarning %}
{% labs %}
Requires the **Feature Name** Labs preview feature. Enable it at {% my labs title="**Settings** > **System** > **Labs**" %}.
{% endlabs %}
Use the example text box to provide interactive syntax highlighting for actions, automations, conditions, scripts, templates, triggers, and template output.
{% example %}
automation: |
alias: "Match fan to ceiling light"
triggers:
- trigger: light.brightness_changed
target:
entity_id: light.living_room_ceiling
options:
threshold: 10
actions:
- action: fan.set_percentage
target:
entity_id: fan.living_room
data:
percentage: >-
{{ state_attr('light.living_room_ceiling', 'brightness_pct') | int }}
{% endexample %}
Available labels are action, automation, condition, script, template, trigger, and output.
Reusable text
Use {% include integrations/config_flow.md %} for integrations set up through the UI.
Use the configuration_basic block to describe configuration options if an integration is set up via a config flow.
Use the configuration block to describe configuration options if an integration is set up via YAML only.
Images
- Use Markdown syntax for images in general.
- Upload images to the
source/images folder in this repository.
- Do not link to external images.
- To add an image with a caption, use the existing
<p class='img'> HTML pattern.
- To invert image colors in dark mode, use the
invertDark class.
Example:
1. To adjust the light temperature and brightness, move the sliders:
2. Then do this ...
Videos
Use the lite-youtube element for YouTube videos. For videoid, use the part of the YouTube URL that comes after watch?v=. Use videoStartAt only when playback should start at a specific time.
<lite-youtube videoid="ZgoaoTpIhm8"
videoStartAt="3907"
videotitle="Introducing Home Assistant Voice Preview Edition">
</lite-youtube>
