Working with Markdown

When you use XMLUI to create an application's user interface, the Text component enables you to display short-form text. But XMLUI can also support sites like this one, using the Markdown component for long-form text.

There are 156 pages here. Of these, 95 are autogenerated Markdown files that document components, and 61 are handwritten Markdown pages like this one.

How do we know that? This site is an XMLUI app, and the Markdown page you are reading can access global app settings just as the Search component does.

<!-- Search component used in this site's Main.xmlui -->
<Search data="{appGlobals.plainTextContent}" />

XMLUI isn't just a way to build apps like XMLUI Invoice. It's also a way to build websites, like this one, using pages written in Markdown format.

Using the Markdown component

Like every XMLUI app, this site is controlled by a Main.xmlui. In this case Main.xmlui uses core components including App, AppHeader, NavPanel, NavGroup, NavLink, Pages, Page.

The Markdown component that renders this page is invoked from Main.xmlui.

<Page url="/working-with-markdown">
    <DocumentPage url="/pages/working-with-markdown.md"/>
</Page>

DocumentPage is a user-defined component that wraps our site's structure around the contents of the file.

<Component name="DocumentPage">
    <HStack gap="$space-5">
        <VStack width="*">
            <Markdown
                when="{$props.content || $props.url}"
                content="{$props.content}"
                data="{$props.url}" />
            <DocumentLinks />
        </VStack>
        <TableOfContents width="$space-64" when="{mediaSize.sizeIndex > 3 && !$props.hideToc}" maxHeadingLevel="3" />
        <VStack width="$space-64" when="{mediaSize.sizeIndex > 3 && $props.hideToc}" />
    </HStack>
</Component>

TableOfContents is a core component that produces the ToC in the right pane of this page.

DocumentLinks is a user-defined component that introspect's site metadata in order to create the previous / next links at the bottom of the page.

<Component name="DocumentLinks">
 <Theme
   textDecorationLine-Link="none"
   textColor-Link="$textColor-DocumentLinks"
   textColor-Link--hover="textColor-DocumentLinks--hover"
   backgroundColor-ContentSeparator="$backgroundColor-separator-DocumentLinks">
   <ContentSeparator
     marginVertical="$space-6"
     when="{$linkInfo.prevLink || $linkInfo.nextLink}"/>
   <HStack verticalAlignment="center" gap="$space-2">
     <Link when="{$linkInfo.prevLink}" to="{$linkInfo.prevLink.to}">
       <Icon name="chevronleft"/>
       <Text variant="subtitle">
         {$linkInfo.prevLink.label}
       </Text>
     </Link>
     <SpaceFiller/>
     <Link when="{$linkInfo.nextLink}" to="{$linkInfo.nextLink.to}">
       <Text variant="subtitle">
         {$linkInfo.nextLink.label}
       </Text>
       <Icon name="chevronright"/>
     </Link>
   </HStack>
 </Theme>
</Component>

Markdown theming

Native XMLUI components and corresponding Markdown elements share common theme variables. Consider this XMLUI Table that's styled according to the current theme.

<App>
  <Table width="40%" data="{
    [{
      apples: 3,
      pears: 7,
      oranges: 11
    }]
  }"
  >
  <Column bindTo="apples"/>
  <Column bindTo="pears"/>
  <Column bindTo="oranges"/>
  </Table>
</App>

Example: using the Table component

<App>
  <Table width="40%" data="{
    [{
      apples: 3,
      pears: 7,
      oranges: 11
    }]
  }"
  >
  <Column bindTo="apples"/>
  <Column bindTo="pears"/>
  <Column bindTo="oranges"/>
  </Table>
</App>

Now let's create that same table using this markdown syntax.

| apples | oranges | pears
| ---    | ---     | ---
| 3      | 7       | 11

It looks the same.

apples	oranges	pears
3	7	11