Markdown

Markdown renders formatted text using markdown syntax. Use Text for simple, styled text content, and Markdown when you need rich formatting.

Key features:

• Rich formatting: Support for headings, bold, italic, lists, links, images, blockquotes, and code blocks
• Dynamic content: Use @{} binding expressions to inject variables and function results
• File loading: Load Markdown content from external files using the data property
• HTML: Use a subset of HTML directly in Markdown

Acquiring content

You can specify Markdown content in these ways.

The content property

Render Markdown content that you calculate or get from other components.

The data property

Render Markdown content from an URL.

Nested text

Render Markdown content that you place directly in a Markdown component.

Whitespace and special characters

Whitespace is significant in Markdown, for example headers using the # syntax must begin in column 1.

These special XML characters are significant too.

< (less than) - Must be escaped as &lt;
> (greater than) - Must be escaped as &gt;
& (ampersand) - Must be escaped as &amp;
" (double quote) - Must be escaped as &quot; in attributes
' (single quote/apostrophe) - Must be escaped as &apos; in attributes

You can use a CDATA section to avoid having to escape these characters individually.

<Markdown>
  <![CDATA[
  ]]>
</Markdown>

Or, as we have done in this page, you can use a code fence (a block delimited by triple backtics) to preserve them.

Supported elements

The Markdown component supports these basic elements.

• Heading
• Bold
• Italic
• Strikethrough
• Blockquote
• Ordered List
• Unordered List
• Code
• Horizontal Rule
• Link
• Image
• Table

See this markdown guide.

Native HTML

Markdown allows a subset of HTML. For example, while Markdown itself does not support rowspan and colspan in tables, you can use HTML directly.

<App>
  <Markdown>
    <![CDATA[
<table>
  <thead>
    <tr>
      <th colspan="2">Name</th>
      <th>Age</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Jill</td>
      <td>Smith</td>
      <td>43</td>
    </tr>
    <tr>
      <td>Eve</td>
      <td>Jackson</td>
      <td>57</td>
    </tr>
  </tbody>
</table>
    ]]>
  </Markdown>
</App>

<App>
  <Markdown>
    <![CDATA[
<table>
  <thead>
    <tr>
      <th colspan="2">Name</th>
      <th>Age</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Jill</td>
      <td>Smith</td>
      <td>43</td>
    </tr>
    <tr>
      <td>Eve</td>
      <td>Jackson</td>
      <td>57</td>
    </tr>
  </tbody>
</table>
    ]]>
  </Markdown>
</App>

Binding Expressions

Our Markdown component is capable of evaluating binding expressions just as other XMLUI components. Use the @{} syntax to wrap expressions that need to be evaluated.

Objects, functions and arrays will be stringified if you place them in Markdown.

Function calls are executed and their return values inlined as strings into markdown.

Behaviors

This component supports the following behaviors:

Properties

breakMode

default: "normal"

This property controls how text breaks into multiple lines. normal uses standard word boundaries, word breaks long words to prevent overflow, anywhere breaks at any character, keep prevents word breaking, and hyphenate uses automatic hyphenation. When not specified, uses the default browser behavior or theme variables.

Available values:

<App>
  <VStack gap="16px">
    <VStack gap="8px">
      <Text variant="strong">breakMode="normal" (default)</Text>
      <Markdown
        width="200px"
        backgroundColor="lightblue"
        padding="8px"
        breakMode="normal">
        <![CDATA[
This text uses standardwordbreaking at natural boundaries like spaces and hyphens.
        ]]>
      </Markdown>
    </VStack>

    <VStack gap="8px">
      <Text variant="strong">breakMode="word"</Text>
      <Markdown
        width="200px"
        backgroundColor="lightgreen"
        padding="8px"
        breakMode="word">
        <![CDATA[
This text will breakverylongwordswhenneeded to prevent overflow while preserving readability.
        ]]>
      </Markdown>
    </VStack>

    <VStack gap="8px">
      <Text variant="strong">breakMode="anywhere"</Text>
      <Markdown
        width="200px"
        backgroundColor="lightyellow"
        padding="8px"
        breakMode="anywhere">
        <![CDATA[
Thistext willbreakanywhereif neededtofit thecontainer eveninthe middleofwords.
        ]]>
      </Markdown>
    </VStack>
  </VStack>
</App>

<App>
  <VStack gap="16px">
    <VStack gap="8px">
      <Text variant="strong">breakMode="normal" (default)</Text>
      <Markdown
        width="200px"
        backgroundColor="lightblue"
        padding="8px"
        breakMode="normal">
        <![CDATA[
This text uses standardwordbreaking at natural boundaries like spaces and hyphens.
        ]]>
      </Markdown>
    </VStack>

    <VStack gap="8px">
      <Text variant="strong">breakMode="word"</Text>
      <Markdown
        width="200px"
        backgroundColor="lightgreen"
        padding="8px"
        breakMode="word">
        <![CDATA[
This text will breakverylongwordswhenneeded to prevent overflow while preserving readability.
        ]]>
      </Markdown>
    </VStack>

    <VStack gap="8px">
      <Text variant="strong">breakMode="anywhere"</Text>
      <Markdown
        width="200px"
        backgroundColor="lightyellow"
        padding="8px"
        breakMode="anywhere">
        <![CDATA[
Thistext willbreakanywhereif neededtofit thecontainer eveninthe middleofwords.
        ]]>
      </Markdown>
    </VStack>
  </VStack>
</App>

content

This property sets the markdown content to display. Alternatively, you can nest the markdown content as a child in a CDATA section. In neither this property value nor any child is defined, empty content is displayed.

Use this property when the text you provide is not static but a result of calculations (you assemble the text or get it from other components).

grayscale

This boolean property specifies whether images should be displayed in grayscale. If set to true, all images within the markdown will be rendered in grayscale.

openLinkInNewTab

This boolean property specifies whether links should open in a new tab. If set to true, all links within the markdown will open in a new tab with target="_blank". Links that explicitly specify their own target using the | target=... syntax will override this setting.

overflowMode

default: "not specified"

This property controls how text overflow is handled. none prevents wrapping and shows no overflow indicator, ellipsis shows ellipses when text is truncated, scroll forces single line with horizontal scrolling, and flow allows multi-line wrapping with vertical scrolling when needed. When not specified, uses the default text behavior.

Available values:

<App>
  <VStack gap="16px">
    <VStack gap="8px">
      <Text variant="strong">overflowMode="flow"</Text>
      <Markdown
        width="300px"
        backgroundColor="lightblue"
        padding="8px"
        overflowMode="flow">
        <![CDATA[
This markdown content wraps to multiple lines naturally. It can contain **bold text**, *italic text*, and even [links](https://example.com), all wrapping as needed.

When you have comma-separated lists like: [reference-1](url1), [reference-2](url2), [reference-3](url3), [reference-4](url4), they will wrap appropriately.
        ]]>
      </Markdown>
    </VStack>

    <VStack gap="8px">
      <Text variant="strong">overflowMode="scroll"</Text>
      <Markdown
        width="300px"
        backgroundColor="lightgreen"
        padding="8px"
        overflowMode="scroll">
        <![CDATA[
This text stays on a single line with horizontal scrolling when content overflows the container width.
        ]]>
      </Markdown>
    </VStack>

    <VStack gap="8px">
      <Text variant="strong">overflowMode="ellipsis"</Text>
      <Markdown
        width="300px"
        backgroundColor="lightyellow"
        padding="8px"
        overflowMode="ellipsis">
        <![CDATA[
This text truncates with ellipsis when it exceeds the container width.
        ]]>
      </Markdown>
    </VStack>
  </VStack>
</App>

<App>
  <VStack gap="16px">
    <VStack gap="8px">
      <Text variant="strong">overflowMode="flow"</Text>
      <Markdown
        width="300px"
        backgroundColor="lightblue"
        padding="8px"
        overflowMode="flow">
        <![CDATA[
This markdown content wraps to multiple lines naturally. It can contain **bold text**, *italic text*, and even [links](https://example.com), all wrapping as needed.

When you have comma-separated lists like: [reference-1](url1), [reference-2](url2), [reference-3](url3), [reference-4](url4), they will wrap appropriately.
        ]]>
      </Markdown>
    </VStack>

    <VStack gap="8px">
      <Text variant="strong">overflowMode="scroll"</Text>
      <Markdown
        width="300px"
        backgroundColor="lightgreen"
        padding="8px"
        overflowMode="scroll">
        <![CDATA[
This text stays on a single line with horizontal scrolling when content overflows the container width.
        ]]>
      </Markdown>
    </VStack>

    <VStack gap="8px">
      <Text variant="strong">overflowMode="ellipsis"</Text>
      <Markdown
        width="300px"
        backgroundColor="lightyellow"
        padding="8px"
        overflowMode="ellipsis">
        <![CDATA[
This text truncates with ellipsis when it exceeds the container width.
        ]]>
      </Markdown>
    </VStack>
  </VStack>
</App>

For comma-separated markdown links (common in reference lists), use overflowMode="flow" with optional breakMode="word":

<App>
  <Markdown
    width="400px"
    backgroundColor="lavender"
    padding="8px"
    overflowMode="flow"
    breakMode="word">
    <![CDATA[
[issue #123](https://example.com/issue/123), [PR #456](https://example.com/pr/456), [issue #789](https://example.com/issue/789), [PR #1011](https://example.com/pr/1011), [issue #1213](https://example.com/issue/1213)
    ]]>
  </Markdown>
</App>

<App>
  <Markdown
    width="400px"
    backgroundColor="lavender"
    padding="8px"
    overflowMode="flow"
    breakMode="word">
    <![CDATA[
[issue #123](https://example.com/issue/123), [PR #456](https://example.com/pr/456), [issue #789](https://example.com/issue/789), [PR #1011](https://example.com/pr/1011), [issue #1213](https://example.com/issue/1213)
    ]]>
  </Markdown>
</App>

removeBr

default: false

This boolean property specifies whether <br> (line break) elements should be omitted from the rendered output. When set to true, <br/> tags in the markdown content will not be rendered. When false (default), <br/> tags render as horizontal bars.

removeIndents

default: true

This boolean property specifies whether leading indents should be removed from the markdown content. If set to true, the shortest indent found at the start of the content lines is removed from the beginning of every line.

<App layout="horizontal-sticky" padding="1rem">
  <Markdown removeIndents="true">
    <![CDATA[
      # My Adventure in Markdown Land

      ## The Beginning

      In the bustling city of Markdownville, I embarked on a journey to
      discover the secrets of Markdown. My adventure started in the heart
      of the city, where the first rule of Markdown was inscribed in stone.
    ]]>
  </Markdown>
</App>

<App layout="horizontal-sticky" padding="1rem">
  <Markdown removeIndents="true">
    <![CDATA[
      # My Adventure in Markdown Land

      ## The Beginning

      In the bustling city of Markdownville, I embarked on a journey to
      discover the secrets of Markdown. My adventure started in the heart
      of the city, where the first rule of Markdown was inscribed in stone.
    ]]>
  </Markdown>
</App>

showHeadingAnchors

This boolean property specifies whether heading anchors should be displayed. If set to true, heading anchors will be displayed on hover next to headings.

If this property is not set, the engine checks if showHeadingAnchors flag is turned on in the global configuration (in the appGlobals configuration object) and displays the heading anchor accordingly.

truncateLinks

This boolean property specifies whether long links should be truncated with ellipsis. If set to true, links will be displayed with a maximum width and overflow will be hidden with text-overflow: ellipsis.

<App>
  <Markdown truncateLinks="true">
    <![CDATA[
This is a long link truncated for display: https://playground.xmlui.org/#/playground/#H4sIAAAAAAAAE1VSS2vjMBD%2BK2LIYRdsy7u0F%2BEGlvbYPSXspQmLYo0dUXskpHHqNvi%2FL1Lchd7m9T1mmCtE1mT04AhBXUF7DwqaX95vDyRE82wjC6NZPxzgzOyjklJ7W3E3VL27VNOrHCyhHJ1BydMJZWTNUzxAxgshmj3OvL1uLONYkR5xUWLNEnKXxzG%2B1MfqBt3hBYPl9yeMbbCeraOlkZklW5LJ0%2FZAjby5hAJaN3pHSBxBvRxTTp3t0z5JEBQ8OzKOxH46obgpQgF8xhET4grWgIJ5HCZbGtemJs6MZOJnOYsMLoCCTQ5KH%2Byow3t5X9efXH90iEm0c8Q7%2B5GEf9z5GQo46fa1D24i85jBaZuydSaNhP70rQtuFCtxnEKnWyx%2F1rUIohcnIUVd3X2HArw2xlL%2FBb6JPk3Xf%2B9hWY7LUoDLN7s5sTOaffIGqtNDxALim%2FYezf%2FcB7xYfPud2daaCxaJdaIBBWcX7Icj1gMUoFu2F1wpv55sbeVPgsH2Z85XI0ZiUPm1luUfOQ4%2BonECAAA%3D
    ]]>
  </Markdown>
</App>

<App>
  <Markdown truncateLinks="true">
    <![CDATA[
This is a long link truncated for display: https://playground.xmlui.org/#/playground/#H4sIAAAAAAAAE1VSS2vjMBD%2BK2LIYRdsy7u0F%2BEGlvbYPSXspQmLYo0dUXskpHHqNvi%2FL1Lchd7m9T1mmCtE1mT04AhBXUF7DwqaX95vDyRE82wjC6NZPxzgzOyjklJ7W3E3VL27VNOrHCyhHJ1BydMJZWTNUzxAxgshmj3OvL1uLONYkR5xUWLNEnKXxzG%2B1MfqBt3hBYPl9yeMbbCeraOlkZklW5LJ0%2FZAjby5hAJaN3pHSBxBvRxTTp3t0z5JEBQ8OzKOxH46obgpQgF8xhET4grWgIJ5HCZbGtemJs6MZOJnOYsMLoCCTQ5KH%2Byow3t5X9efXH90iEm0c8Q7%2B5GEf9z5GQo46fa1D24i85jBaZuydSaNhP70rQtuFCtxnEKnWyx%2F1rUIohcnIUVd3X2HArw2xlL%2FBb6JPk3Xf%2B9hWY7LUoDLN7s5sTOaffIGqtNDxALim%2FYezf%2FcB7xYfPud2daaCxaJdaIBBWcX7Icj1gMUoFu2F1wpv55sbeVPgsH2Z85XI0ZiUPm1luUfOQ4%2BonECAAA%3D
    ]]>
  </Markdown>
</App>

Events

This component does not have any events.

Exposed Methods

This component does not expose any methods.

Styling

The component itself cannot be styled, but the components that render the final text have customizable style variables.

Text Heading Link Image Checkbox

Theme Variables