Markdown

Markdown displays plain text styled using markdown syntax.

Using Markdown

The Markdown component allows you to specify its textual content in two ways:

  • You can leverage the content property. 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).
  • You declare nested text.

As whitespaces (such as spaces and line breaks) have significance in Markdown, you should wrap the text between the <![CDATA[ and ]]> XMLUI tags, which preserve all whitespaces.

Indentation is also essential in Markdown. Start the markdown text in the first column as the following sample shows:

<App layout="horizontal-sticky">
  <Markdown>
    <![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:
 
"To create a heading, add number signs (#) in front of a word or phrase.
The number of number signs you use should correspond to the heading level."
 
Headings give hierarchy to text but sometimes **emphasizing something with bold 
is just enough**.
 
If not bold, then simply *italic letters give visual diversity*.
 
## Exploring Blockquotes
 
As I journeyed further, I encountered blockquotes that spoke of the beauty of 
simplicity:
 
> Blockquotes can contain multiple paragraphs. Add a > on the blank lines between 
> the paragraphs.
> > Like so
 
## The Power of Lists
 
I also discovered the power of lists, which were as versatile as the inhabitants 
of Markdownville:
 
- This is the first list item.
- Here's the second list item.
    - A subsection here would look great below the second list item.
- And here's the third list item.
 
I found that I can create ordered lists as well:
 
1. The first item.
2. The second item.
3. Third item.
 
## The Image
 
Text is not the only thing I found through my journey. The power of images 
materialized in front of me:
 
![Colors image](/resources/images/components/markdown/colors.png)
 
## Navigating with Hyperlinks
 
Hyperlinks, like signposts, marked other paths that branched off from the road 
I was treading:
- [Source of all truth](https://github.com/xmlui-com/xmlui)
- [Back to where we started](https://ncrm.azurewebsites.net/)
 
## The Horizontal Rule
 
In the quiet corners of Markdownville, I found the Horizontal Rule, a line that 
symbolizes the end of a section:
 
***
    ]]>
  </Markdown>
</App>

The Markdown component supports these syntax elements:

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

WIP elements:

  • Table (GFM syntax)
  • Tasklist (GFM syntax)
  • Footnote (GFM syntax)

GFM stands for Github Flavored Markdown

These are also found in the Basic Syntax table of this markdown guide (opens in a new tab). Note that further components may be added later, like elements from the Github Flavored Markdown or GFM syntax (opens in a new tab).

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.

Empty ${} expressions are removed. 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.

<App>
  <variable name="x" value="{() => { return 'testing' }}" />
  <Markdown>
    <![CDATA[
  Empty elements are removed: ${}
 
  Nested objects and functions are handled: ${ { a: 1, b: () => {} } }
 
  Function calls are executed: ${x()}
    ]]>
  </Markdown>
</App>

Properties

content

This property sets the markdown content to display.

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).

<App>
  <VStack>
    <Items data="{[
      {id: 123, name: 'Peter Parker'},
      {id: 234, name: 'Clark Kent'},
      {id: 345, name: 'Bruce Wayne'}
    ]}">
      <Markdown content="{'## ' + $item.id + '\\n*' + $item.name + '*' }"/>
    </Items>
  </VStack>
</App>

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>

Events

This component does not have any events.

Exposed Methods

This component does not expose any methods.

Styling

The component itself cannot be styled.

However, the components that are used render the final text, have customizable style variables.

The components used to render the final styled text are either used as regular XMLUI components. See the links for styling details: Text Heading Link Image Checkbox

Or they are components specifically created and used in the Markdown component.

📔

Components falling into this latter case are only available under the Markdown component. They cannot be instantiated in regular XMLUI.

These markdown-specific components are the following:

Blockquote

A blockquote is a sentence or paragraph specially formatted to draw attention to the reader. You can use the following theme variables with blockquotes:

  • accent-Blockquote: sets the color of the strip running down on the left side of the block
  • backgroundColor-Blockquote: sets the background color
  • margin-Blockquote: sets the margin
  • padding-Blockquote: sets the padding
  • borderRadius-Blockquote: sets the radius of the border for the block
  • boxShadow-Blockquote: specifies the x offset, y offset, blur radius and color for the block shadow

Use a theme that sets these theme variable values:

{
  "id": "custom",
  "name": "Custom Theme",
  "themeVars": {
    "accent-Blockquote": "transparent",
    "backgroundColor-Blockquote": "rgba(27, 195, 50, 0.3)",
    "margin-Blockquote": "8px",
    "padding-Blockquote": "16px",
    "borderRadius-Blockquote": "8px",
    "boxShadow-Blockquote": "5px 10px 5px green"
  }
}
<App>
  <Markdown>
    <![CDATA[
> This text is in a blockquote.
> > This one has an even bigger emphasis, since it is nested.
> > > This one is nested even deeper.
> Continue the original block.
    ]]>
  </Markdown>
</App>

HorizontalRule

This element visually separates content. The following theme variables influence how the rule looks like:

  • borderColor-HorizontalRule: changes the color
  • borderStyle-HorizontalRule: changes the border style to any CSS border style (opens in a new tab), default is solid
  • borderWidth-HorizontalRule: changes how tall the rule should be, default is 1px

Check this sample:

{
  "id": "custom",
  "name": "Custom Theme",
  "themeVars": {
    "borderColor-HorizontalRule": "red",
    "borderWidth-HorizontalRule": "8px",
    "borderStyle-HorizontalRule": "dotted"
  }
}
<App>
  <Markdown>
    <![CDATA[
Section 1
 
---
 
Section 2
    ]]>
  </Markdown>
</App>
📔

The HorizontalRule component looks similar to the ContentSeparator component. They are not the same and are styled separately.

ListItem

These are the supported theme variables in an ordered or unordered list:

  • paddingLeft-ListItem: determines how big the gap should be between the list item contents and the item marker

Here is a sample:

{
  "id": "custom",
  "name": "Custom Theme",
  "themeVars": {
    "paddingLeft-ListItem": "40px"
  }
}
<App>  
  <Markdown>
    <![CDATA[
1. Get in the driver's seat and buckle up
2. Insert the key into the ignition
3. Put the gearstick in either the "P" or "N" position
4. Twist the ignition key to start the car
    ]]>
  </Markdown>
</App>

OrderedList

This element represents an ordered list with Arabic numbers as markers. Lists can be nested into one another; the counter will start anew if nested. Ordered lists support these theme variables:

  • paddingLeft-OrderedList: determines how much space the list should have from the left

Check this sample:

{
  "id": "custom",
  "name": "Custom Theme",
  "themeVars": {
    "paddingLeft-OrderedList": "80px"
  }
}
<App>
  <Markdown>
    <![CDATA[
1. Get in the driver's seat and buckle up
2. Insert the key into the ignition
3. Put the gearstick in either the "P" or "N" position
4. Twist the ignition key to start the car
    ]]>
  </Markdown>
</App>

UnorderedList

This element represents an unordered list with marker symbols. Lists can be nested into one another; different levels of nested lists will have different markers. These are the theme variables unordered lists support:

  • paddingLeft-UnorderedList: determines how much space the list should have from the left

Look at this example:

{
  "id": "custom",
  "name": "Custom Theme",
  "themeVars": {
    "paddingLeft-UnorderedList": "80px"
  }
}
<App>
  <Markdown>
    <![CDATA[
- Get in the driver's seat and buckle up
- Insert the key into the ignition
- Put the gearstick in either the "P" or "N" position
- Twist the ignition key to start the car
- Know that cars may refuse to start for any number of reasons
    - Consult your car's manual
    - Take your car to a mechanic
        - If all else fails, troubleshoot the car yourself
    ]]>
  </Markdown>
</App>