# Use Markdown and HTML

Source: https://govform.com/resources/documentation/article/12-use-markdown-and-html
Topic: Practical guides

Use **Text** mode for ordinary wording and formatting. Its toolbar formats content and inserts answers while retaining Liquid expression chips and completions. **MD** and **HTML** expose the source for advanced edits.

## Choose the right content mode

| View | Use | What it changes |
| --- | --- | --- |
| Text | Ordinary content editing, formatting and inserting answers. | A formatted source view, not a rendered service preview. It does not execute Liquid or arbitrary HTML/CSS. |
| MD | Markdown source for headings, lists, links, emphasis and supported embedded HTML. | The saved interpretation is Markdown. |
| HTML | Semantic source for a structure that needs HTML. | The saved interpretation is HTML; Markdown syntax is not processed. |

Text/source views share the source, selection and undo history. Switching views does not convert or save the content. The selected view is remembered for the browser session; newly created content starts in Text while untouched content may open in its source view. In service JSON, `markdownMode` remains `markdown` or `html`; there is no text value. Use Preview/User view to check evaluated content.

## Write clear Markdown first

Use a short heading hierarchy that reflects the information people need. Start with a page heading, then use subheadings to break up meaningful sections. Do not choose a heading only because it looks visually prominent; headings help people scan the page and navigate with assistive technology.

```
## Before you start

You will need your reference number and supporting documents.

- Keep this page open while you find the documents.
- You can save your progress and return later.

For help, [contact the service team](https://example.org/help).
```

Choose descriptive link text that still makes sense out of context. For example, use **Contact the service team** rather than **Click here**. Keep a list as a list; do not imitate bullets with line breaks or punctuation. Use a table only where people genuinely need to compare values across rows and columns.

## Use HTML for structure, not decoration

Some Builder content patterns are created as HTML because they need a particular structure, such as a table, tab set, accordion or summary pattern. If you use HTML, begin with semantic elements and make the order understandable without visual styling.

```
<section aria-labelledby="evidence-heading">
  <h2 id="evidence-heading">Evidence you need</h2>
  <p>Upload a copy of each document that supports your application.</p>
</section>
```

Avoid adding scripts, inline event handlers or unreviewed interactive code. Do not use colour, position, icons or styling as the only way to communicate an instruction, status or error. If a visual pattern carries important meaning, provide that meaning in text as well.

## Keep HTML mode intentionally compact

In Markdown mode, blank lines can cause Markdown processing to treat sections of HTML as separate blocks, which can break a complex pattern. When a pattern is intended to be raw HTML, select **HTML** mode and keep the markup complete and valid. Do not switch to HTML mode merely to avoid learning Markdown; it makes ordinary updates less accessible to non-technical editors.

```
flowchart TD
    A["Write the message"] --> B{"Can Markdown express the structure?"}
    B -->|"Yes"| C["Use Markdown mode"]
    B -->|"No"| D["Use semantic HTML mode"]
    C --> E["Preview with realistic values"]
    D --> E
    E --> F["Test reading order and interaction in User view"]
```

## Combine formatted content with Liquid carefully

Liquid is evaluated before the formatted content is rendered. A dynamic value can therefore change the Markdown or HTML that the person sees. Test with a typical value, a long value, an empty value, punctuation, quotation marks and non-English characters.

For example, this content uses an answer in a paragraph:

```
## Your application

You told us the application type is **{{ applicationType }}**.
```

Do not allow dynamic content to create broken links, malformed HTML attributes, invalid JSON or accidental markup. Use a fallback for optional values, and treat content from an external source or a person’s input as untrusted unless it has been safely handled for its destination.

## Check accessibility before release

Formatted content needs the same quality checks as the rest of the journey.

-   Read headings and links in order; they should describe the content and destination clearly.
-   Use meaningful table headers and avoid tables for layout.
-   Check the page at 200% zoom and on a narrow viewport.
-   Use the keyboard to reach and operate any interactive HTML pattern.
-   Check that an icon or colour is not the only source of meaning.
-   Test dynamic content with a screen reader where the content is important to completing the service.

Preview the complete page in User view, then repeat the relevant checks in QA. A content component may look correct in the editor while dynamic values or a different viewport expose a problem in the actual journey.

## Related guides

-   [Add and configure components](<https://govform.com/resources/documentation/article/06-add-and-configure-components>)
-   [Write Liquid templates](<https://govform.com/resources/documentation/article/11-write-liquid-templates>)
-   [Design accessible services](<https://govform.com/resources/documentation/article/14-design-accessible-services>)
-   [Test, deploy and maintain a service](<https://govform.com/resources/documentation/article/13-test-deploy-and-maintain-a-service>)