Documentation

Markdown & MDX

Titles and headings

All content pages start with a title, followed by the subtitle and content. The title is defined using the title key in the frontmatter of the MDX file, followed by the subtitle, defined using the <Subtitle> tag.

---
title: Title of the page
---


<Subtitle>


Short sentence with the main use case and benefits of the feature.


</Subtitle>


# Headers


You can use standard Markdown syntax for headings.


The first line of content is closely bound to the heading with a smaller margin. Heading levels 1,2, and 3 appear in the right-hand index navigation by default, which helps readers understand the page's content without reading or scrolling through them.


# Level 1 heading


They have the biggest font than other headings, and bound to the left margin of the page.


## Level 2 heading


They have a smaller font than the level 1 headings, and are also bound to the left margin of the page.


### Level 3 heading


They have the smallest font compared to the other headings, and are slightly indented to th right from the left margin of the page.


#### Level 4 heading


Any headings after level 3 are rendered and aligned the same as level 3 headings, but do not appear on the right-hand index navigation as level 3 headings.

The rendered page can be seen here.

Avoid using links, code formatting, or any other style in headings.

Text formatting

You can use standard Markdown syntax for formatting text.

  • Bold text

    **Bold text**

  • Italicized text

    _Italicized text_

  • Bold and italicized text

    _**Bold and italicized text**_

  • Monospaced text

    `Monospaced text`

Paragraph break

Add a blank line to introduce paragraph breaks.


This is how a paragraph break is rendered.

Add a blank line to introduce paragraph breaks.

This is how a paragraph break is rendered.

Line break

Add a `\` at the end of a sentence to introduce a line break.\
This is how a line break is rendered.

Add a \ at the end of a sentence to introduce a line break.
This is how a line break is rendered.

Bulleted list

Use bulleted lists to list items that have no particular order or sequence.


- Item 1
  - Sub-item 1
- Item 2

Use bulleted lists to list items that have no particular order or sequence.

  • Item 1
    • Sub-item 1
  • Item 2

Numbered list

Use numbered lists to list items that follow a particular order or sequence.


1. Step 1
2. Step 2

Use numbered lists to list items that follow a particular order or sequence.

  1. Step 1
  2. Step 2

Tables

We strongly prefer bulleted lists to tables for consistency, visual styling, and Markdown formatting reasons.

| Column A | Column B | Column C |
| -------- | -------- | -------- |
| A1       | B1       | C1       |
| A2       | B2       | C2       |
| A3       | B3       | C3       |
Column AColumn BColumn C
A1B1C1
A2B2C2
A3B3C3

Special mentions

Special mentions are limited to Info or Warning boxes in our documentation. Place them (before or after a sentence) in relevance to the context being discussed for better clarity. Limit the usage of notices, to where necessary, to avoid reducing its effectiveness in emphasizing important information.

  • Info box

    An Info box is used to:

    • emphasize points or reminders.
    • point out exceptions from the standard behavior described in the respective section.
    • indicate possible side effects that are not obvious or expected in the first place.

  • Warning box

    A Warning box is used to warn users about the possibility of issues or data loss.

When using Markdown syntax within, leave an empty line between the content and element tags for the formatting to render.

Multiple paragraphs:

<Info>


Paragraph A


Paragraph B


</Info>

Paragraph A

Paragraph B

Bulleted list:

<Info>


- Item A
- Item B


</Info>
  • Item A
  • Item B

Ordered list:

<Info>


1. Item A
2. Item B


</Info>
  1. Item A
  2. Item B

Code block:

<Info>


```
a code block
```


</Info>
a code block

Table:

<Info>


| Column A | Column B | Column C |
| -------- | -------- | -------- |
| A1       | B1       | C1       |
| A2       | B2       | C2       |
| A3       | B3       | C3       |
</Info>
Column AColumn BColumn C
A1B1C1
A2B2C2
A3B3C3

Custom anchors

Anchor in a line

[This link jumps to the anchored line.](#any-html-id-compatible-string-expected-usage)


The anchor is placed in this line. <Anchor name="any-html-id-compatible-string-expected-usage" />

This link jumps to the anchored line.

The anchor is placed in this line.

Anchor in a title

[This link jumps to the anchored title.](#any-html-id-compatible-string-in-a-title)


### The anchor is placed in this title <Anchor name="any-html-id-compatible-string-in-a-title" />

This link jumps to the anchored title.

The anchor is placed in this title

Anchor in a list

[This link jumps to the anchored item in the list.](#any-html-id-compatible-string-in-a-list)


- Item 1 <Anchor name="any-html-id-compatible-string-in-a-list" />
- Item 2

This link jumps to the anchored item in the list.

  • Item 1
  • Item 2

Cards

A card, by default, is flat and of regular width. Two regular cards and three narrow cards can be stacked side by side (except in mobile viewports) in microsite landing pages. You can also use a narrow card of reduced width by passing narrow in the syntax. It is also possible to make these cards clickable by passing clickable in the syntax.

  • Flat - Use case
  • Clickable - Use case
  • Regular - Use case
  • Narrow - Use case

The following properties can be used to define the content within the card:

  • fitContentColumn (boolean): automatically set to cards on landing pages. However, it is rendered differently for cards used in content pages.

  • title (string): use to set a title for a card, no Markdown allowed.(Does "no markdown" mean that formatting isn't applicable?)

    • smallTitle (boolean): use to reduce and set a smaller font size to card titles.

  • textLink (string): use to set the bottom link text. If not set, the bottom link is not rendered at all.

  • href (string): use to set the target of the bottom link and whole card (if clickable is set). If clickable or textLink isn't set, href has no effect.

  • icon (component): use to reserve a 48x48px space for an icon in the card.

  • image (component): use to reserve a define pixels space for an image in the card.

Cards with no properties defined

This is an example of a set of cards with no properties defined. It is flat and of regular width as the parameters clickable and narrow are not defined. It only contains the body as title is not defined.

<Cards>
  <Card>Card A</Card>
  <Card>Card B</Card>
  <Card>Card C</Card>
  <Card>Card D</Card>
</Cards>

  • Card A

  • Card B

  • Card C

  • Card D

Cards with a list in the body

It is also possible to have a list in the body of the card. Lists are usually used in flat cards as you can provide multiple target links for multiple list entries, which is not the case for clickable cards that have only one target link.

<Cards>
  <Card title="Card with bullet list">
    - Item 1 - Item 2 - Sub-item 1 - Item 3
  </Card>
</Cards>
  • Card with bullet list
    • Item 1
    • Item 2
      • Sub-item 1
    • Item 3

Flat card

<Cards>
  <Card
    title="Title of the card"
    href="/writing/navigation"
    textLink="Read more about navigation"
  >
    In a flat card, only the target link is clickable.
  </Card>
</Cards>

Clickable card

Clickable cards must have a href set.

They have one card-level target link (href) and no other links in the content. The target link (href) can be repeated as a link at the bottom by setting a card link label.

<Cards clickable>
  <Card
    title="Title of the card"
    href="/writing/navigation"
    textLink="Read more about navigation"
  >
    In a clickable card, the complete card is a clickable target.
  </Card>
</Cards>

Cards with an image

Images are not supported for free-form in-content cards, but only in places that are fully designed and implemented by developers. An image is sized into the width of the card.

Flat card

<Cards>
  <Card title="Title of the card" image={<CardBannerOSSIcon />}>
    Flat card with an image
  </Card>
</Cards>
  • Title of the card

    Flat card with an image

Clickable card

<Cards clickable>
  <Card
    title="Title of the card"
    href="/writing/navigation"
    image={<CardBannerMcDevsIcon />}
  >
    Clickable card with an image
  </Card>
</Cards>

Cards with an icon

Only icons provided in the UI Kit are supported. They fit in a 48x48px square aligned at the top or left of a card.

Flat card

<Cards>
  <Card
    title="Title of the card"
    icon={<DummyIcon />}
    href="/writing/navigation"
    textLink="Read more about images"
  >
    Icons in regular cards are aligned to the top regardless of whether they are
    clickable or flat.
  </Card>
</Cards>
  • Title of the card

    Icons in regular cards are aligned to the top regardless of whether they are clickable or flat.

    Read more about images

Clickable card

<Cards narrow clickable>
  <Card
    title="Title of the card"
    href="/writing/navigation"
    textLink="Read more about images"
    icon={<DummyIcon />}
  >
    Icons in narrow cards are aligned to the left regardless of whether they are
    clickable or flat.
  </Card>
</Cards>

Cards with an image and icon

Regular card

<Cards>
  <Card image={<CardBannerMcDocsIcon />} icon={<DummyIcon />}>
    Regular card with an image and icon
  </Card>
</Cards>

  • Regular card with an image and icon

Narrow card

<Cards narrow>
  <Card image={<CardBannerPlatformIcon />} icon={<DummyIcon />}>
    Narrow card with an image and icon
  </Card>
</Cards>

  • Narrow card with an image and icon

RSS feed

RSS feed is an online file that notifies users of our latest content updates.

RSS feeds are only generated in production builds.

Table with one feed

<RssFeeds dataSources={[
"/docs-smoke-test/releases/feed.xml"
]}/>

Table with multiple feeds

<RssFeeds
  dataSources={[
    '/docs-smoke-test/releases/feed.xml',
    '/api-docs-smoke-test/releases/feed.xml',
  ]}
/>