Markdown & MDX

Frontmatter, Title

Content pages typically have a title, followed by the subtitle and content. The title is defined using the title key in the frontmatter of the MDX file. "Frontmatter" is a block of yaml syntax data properties at the top of an MDX file, enclosed by lines with three minus-dash signs.

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>

Start content here.

Headings

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.

Text formatting

You can use standard Markdown syntax for formatting text.

Bold text

**Bold text**

Italicized text

_Italicized text_

_**Bold and italicized text**_

Monospaced Text

Monospaced Text is to be used for string literals, that is cases where the communication is not intended by the meaning of the word but to be the exact character sequence as displayed. Typical examples are inline code spans like shell commands, file names, folder paths, but also constant values.

`Monospaced text`

Paragraph break

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.

Bulleted list

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

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       |

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.

When using Markdown syntax within, you must leave an empty line between the content and element tags for the formatting to render. Nearly all Markdown is possible inside Special Mentions but only text microformatting and lists are recommended.

Info box

<Info>

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.

</Info>

Warning box

<Warning>

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

</Warning>

Links

Link URLs have to follow a defined convention depending on whether they point to the same microsite, a different docs-kit microsite or to an external location. They are rendered differently based on the target and analytics tracking is added depending on the target.

Link to an external website

[Link to commercetools' marketing website](https://commercetools.com)

Link to a heading or other anchor on the same page

[how to write links](#links)

Link to another page on this site

[writing pages](/writing/pages)

[writing pages - markdown frontmatter section](/writing/pages#markdown-frontmatter)

Link to a page of another docs microsite

[A link to the '/views/links' path in the `docs-smoke-test` microsite](/../docs-smoke-test/views/links)

Technically, this is navigation into a "negative" path depth. In development mode this will not be working link target, but in production the site is hosted inside a subfolder of the main domain, so this pattern is navigating out of the current website into the main domain and then into the other microsite.

Link to static files

[Link](/downloads/hello.txt)

Custom link targets

The <Anchor> component allows to create invisible link targets at any place in the content. It allows to create links to places that are not a heading - headings have an autogenerated "anchor" to link to them.

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

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

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

- Item 1 <Anchor name="any-html-id-compatible-string-in-a-list" />
- 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>

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>

Cards with a link

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

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>

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

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>

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>

Narrow card

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

RSS feed

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

List from one feed

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

List from multiple feeds

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