Markdown

Markdown & MDC Syntax

The Dev Portal utilizes Markdown to compose custom pages and other content.

For additional functionality, the Portal uses MDC (MarkDown Components) syntax to supercharge regular Markdown, enabling it to leverage the power of Vue components with slots and props.

Components

The Portal exposes a collection of built-in components that can be utilized within your markdown documents.

Block Components

Block components are provided components that accept Markdown content or other block components as their main content, or as "slots."

Every component listed on the docs site here is available for use as a block component in your Markdown files.

In a markdown file, use block components with the :: identifier.

::container
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
::

Slots

A block component's slots can accept raw markdown content or another block component.

Default slot

The default slot renders the top-level content inside the block component.

::container
This will be rendered inside the `default` slot.
::

Named slots

Any named slots use the # identifier to render the corresponding content.

::page-hero
#title
Title slot text

#description
This will be rendered inside the `description` slot.
::

Nesting

The MDC syntax also supports nesting block components inside slots by indenting them.

::page-section
  :::container
    A nested container.

    ::::container
    A super nested container.
    ::::
  :::
::

Inline Components

Inline components are simply block components that do not contain slots. If a block component supports slots, but you do not need to utilize the slots, you can use the block component as an inline component.

Inline components can be used with the : identifier.

:alert{ appearance="success" message="This is an inline component with inline props." }

If you want to use an inline component followed by specific characters like -, _ or :, you can use a dummy props specifier after it.

:hello{}-world

In this example, :hello{} will search for the <Hello /> component, and -world will be plain text.

Props

There are two ways to pass props to components using MDC.

YAML props

The YAML method uses the --- identifier to declare one prop per line for improved readability.

When providing a string value, it's recommended to double-quote the value, e.g. property: "my value".

::container
---
color: "#fff"
background-image: 
  url: "https://i.imgur.com/rU6cP5h.jpeg"
  background-size: "cover"
border: "1px solid lightgray"
border-radius: "8px"
padding: "50px 20px"
---
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
::

Inline props

The {} identifier passes props to components in a terse way by using a key=value syntax. Multiple props can be separated with a space.

::alert{ appearance="success" title="Awesome!" }
This is the **alert** component.
::

The v-bind shorthand : can also be used to bind a prop to a value in the front matter, or if the prop value should be interpreted as a non-string value such as a boolean or number.

::alert{ appearance="info" :show-icon="true" }
This alert has an **icon**.
::

If you want to pass arrays or objects as props to components you can pass them as a JSON string and prefix the prop key with a colon to automatically decode the JSON string. Note that in this case you should use single quotes for the value string so you can use double quotes to pass a valid JSON string

<!-- Array -->
:fake-component{:items='["One", "Two", "Three"]'}

<!-- Array of Numbers -->
:fake-component{:items='[1, 2, 3]'}

<!-- Object -->
:fake-component{:options='{"responsive": true, "scales": {"y": {"beginAtZero": true}}}'}

Span Text

To create inline spans in your markdown text you can use the [] identifier.

Check out our [brand new]{style="background-color:lightcoral; padding: 2px 4px;"} portal!

Attributes

Attributes are useful for highlighting and modifying part of paragraph. The syntax is nearly similar to inline components and markdown link syntax.

Possible values are all named attributes, classes with the notation .class-name and an ID with #id-name.

Check out our [brand new]{ .custom-class #custom-id style="background-color:lightcoral; padding: 2px 4px;"} portal!

In addition to MDC components and span, attribute syntax will also work on images, links, inline code, bold and italic text.

Attributes work on:

- ![Kong](/images/examples/kong-icon.svg){style="display: inline; margin: 0;"} images,
- [link](#attributes){style="background-color: pink;"}, `code`{style="color: darkcyan;"},
- _italic_{style="background-color: yellow; color:black;"} and **bold**{style="background-color: lightgreen;"} text.

Binding data in markdown

You can bind data within your Markdown document using the {{ $doc.variable || 'default value' }} syntax. These values can be defined in the YAML front matter at the top of the markdown document.

---
title: "Title of the page"
description: "The meta description of the page"
customVariable: "Custom Value"
---

The title of this page is "{{ $doc.title }}."

The custom variable value is {{ $doc.customVariable || 'not defined' }}.