# Home Assistant Markdown Liquid Style > Home Assistant Markdown Liquid Style is an Agent Skill for documents published in the home-assistant/home-assistant.io repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task. Use this when editing Home Assistant Markdown, Liquid, internal links, images, videos, glossary terms, My links, text boxes, or other website syntax. - Skill name: `home-assistant-markdown-liquid-style` - Category: [Documents](https://www.openparable.com/skill/documents/1) - Source: https://github.com/home-assistant/home-assistant.io/blob/HEAD/.claude/skills/home-assistant-markdown-liquid-style/SKILL.md - Repository: home-assistant/home-assistant.io (9,567 GitHub stars when collected) ## SKILL.md # 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_data` - `site.data.alerts_data` - `site.data.version_data` - `site.data.language_scores` - `site.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](https://www.home-assistant.io/docs/tools/quick-search/#my-links) to open a page in the reader's own Home Assistant installation when that helps them follow a UI path. Example: ```markdown Go to {% my integrations title="**Settings** > **Devices & services**" %} and select your integration. ``` Common My links: ```markdown - {% 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 [] %}` Examples: ```markdown {% 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. ```html A/V MCP RTSP ``` ## Inline icons To refer to an icon in the UI, use icons from the [Iconify library](https://icon-sets.iconify.design/mdi/). Examples: ```markdown - 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. ```markdown {% 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. ```markdown {% 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. ```liquid {% 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 `

` HTML pattern. - To invert image colors in dark mode, use the `invertDark` class. Example: ```markdown 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 ... ``` ## 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. ```html ``` --- Source: https://www.openparable.com/skill/documents/home-assistant-markdown-liquid-style (OpenParable). Cite the canonical URL above.