Use Markdown and HTML

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

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
• Write Liquid templates
• Design accessible services
• Test, deploy and maintain a service