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>
<
## 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 blockbackgroundColor-Blockquote
: sets the background colormargin-Blockquote
: sets the marginpadding-Blockquote
: sets the paddingborderRadius-Blockquote
: sets the radius of the border for the blockboxShadow-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 colorborderStyle-HorizontalRule
: changes the border style to any CSS border style (opens in a new tab), default issolid
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>