# Markdown card

> The Markdown card shows text written in Markdown, rendered as a template, so it can mix fixed text with live states.

Source: https://contributors.home-assistant.io/design/dashboards/markdown-card/

Live demo of `hui-card`, connected to a demo Home Assistant.

```html
<hui-card style="width: 380px" data-props='{"config": {"type": "markdown", "title": "Welcome home", "content": "The **laundry** is almost done.\nDinner is at **seven**, and the shopping list is on the fridge."}}'></hui-card>
```

## Usage

The Markdown card shows text. Use it for a note on the dashboard, like a welcome message, house rules for guests, or instructions next to a device. Because the content is a template, it can also put states into a sentence, like "The front door is closed and it is 12 °C outside."

Reach for it when words say more than a control would. For a single state, a [tile card](https://contributors.home-assistant.io/design/dashboards/tile-card/) or an [entity card](https://contributors.home-assistant.io/design/dashboards/entity-card/) is clearer, and keeps working when someone renames the entity. For a title above a group of cards, use the [heading card](https://contributors.home-assistant.io/design/dashboards/heading-card/), not a Markdown card with a big header.

### Templates

The content is sent to Home Assistant and rendered as a template, every time. The card subscribes to the result, so it updates as soon as a state used in the template changes. A template looks like this:

```jinja
The front door is {{ states("binary_sensor.front_door") }}.
```

Inside the template, `config` holds the configuration of the card, and `user` the name of the person looking at it.

The demos on this site have no Home Assistant behind them to render a template, so they only show plain Markdown.

### Formatting

The card renders Markdown the way the rest of Home Assistant does. A single line break in the content is a line break on the card. Next to the usual Markdown, a few elements of the frontend work, like `<ha-icon>`, `<ha-alert>`, and `<ha-qr-code>`. A blockquote in the GitHub alert style becomes an alert.

Live demo of `hui-card`, connected to a demo Home Assistant.

```html
<hui-card style="width: 380px" data-props='{"config": {"type": "markdown", "content": "> [!TIP]\n> The guest Wi-Fi password is on the back of the router."}}'></hui-card>
```

Only a safe set of HTML is allowed. Scripts, styles, and most other tags are stripped.

### Text only

With `text_only: true`, the card has no background, border, or shadow. The text sits on the dashboard itself. Use it for a line of text between cards, like a short explanation in a section. A title is not shown in this mode.

Live demo of `hui-card`, connected to a demo Home Assistant.

```html
<hui-card style="width: 380px" data-props='{"config": {"type": "markdown", "text_only": true, "content": "Lights in the garden turn on at sunset, and off at midnight."}}'></hui-card>
```

### Actions

The card does nothing when you select it, unless you give it a `tap_action`. Then the whole card becomes a button, with a ripple and a pointer cursor. Use it, for example, to navigate to a view with more details. Don't put links in the text and an action on the card at the same time: people can't tell what will happen where.

### Content

- Keep it short. A card is not a page, and a long text pushes the controls off the screen.
- Write in full sentences, and put states in a sentence instead of a list of raw values.
- Use `show_empty: false` when the template can render nothing, like a reminder that only shows when something needs attention. The card then hides itself.

## Configuration

- `content` (string, required): the Markdown to show. Rendered as a template.
- `title` (string): the title of the card. Not shown with `text_only`.
- `text_only` (boolean): shows the text without the card background, border, and shadow. Defaults to `false`.
- `show_empty` (boolean): shows the card when the content renders as empty. Defaults to `true`.
- `entity_id` (string or list): entities that update the template, for templates where Home Assistant can't work out which entities they use.
- `card_size` (number): the height of the card in the masonry view, in units of 50 pixels. Defaults to half the number of lines.
- `theme` (string): the theme for this card.
- `tap_action`, `hold_action`, `double_tap_action` (action): what happens when you select, hold, or double tap the card. Default to `none`.

```yaml
type: markdown
title: "Garden"
content: >
  The irrigation is **{{ states("valve.garden_irrigation") }}**,
  and it is {{ states("sensor.outdoor_temperature") }} °C outside.
```

## In code

The card lives in [`src/panels/lovelace/cards/hui-markdown-card.ts`](https://github.com/home-assistant/frontend/blob/dev/src/panels/lovelace/cards/hui-markdown-card.ts), and the element is `<hui-markdown-card>`. It renders the content through `subscribeRenderTemplate` from [`src/data/ws-templates.ts`](https://github.com/home-assistant/frontend/blob/dev/src/data/ws-templates.ts), and shows the result with `<ha-markdown>`, the same component the rest of the frontend uses for Markdown. The Markdown is parsed and sanitized in a web worker, [`src/resources/markdown-worker.ts`](https://github.com/home-assistant/frontend/blob/dev/src/resources/markdown-worker.ts), which also holds the list of allowed elements.

When the template has an error, the card shows it in an alert above the text while you edit the card.

[Source](https://github.com/home-assistant/frontend/blob/dev/src/panels/lovelace/cards/hui-markdown-card.ts)