Skip to main content
Version: Next Gen

Markdown Reference Guide

Last updated on

Basic formatting​

FormatSyntax
Bold**Bold**
Italic_Italic_
Strikethrough~~Strikethrough~~
Horizontal rules--- (three hyphens)
*** (three asterisks)
___ (three underscores)

Whichever style you use, pick one and stick with it.
Bold and italic***Bold and italic***
Underline<u>Underline</u>

Headings​

All heading levels (e.g., H1, H2, etc.), are marked by the hashtag (#) at the beginning of a line.

important

Avoid using h1 (#) headings. The metadata tile represents this heading level and is automatically displayed. Always start with h2 (##), and respect the order h2 → h3 → h4. Never skip the hierarchy level, such as h2 → h4. Avoid h5 and h6 as much as possible. If you have content with h5 and h6 headers, rethink the structure of your document. Can the content be better scanned in a table or bullet list?

## This is a second level heading (h2)

### This is a second level heading (h3)

#### This is a second level heading (h4)

Always put a space between the hash tag and the heading name.

✅ DO🚫 DON'T
# Here's a Heading #Here's a Heading

Also, put blank lines before and after a heading.

✅ DO🚫 DON'T
Put a extra space (blank line) before...

# Heading

...and after a heading.
Put a extra space (blank line) before...
# Heading
...and after a heading.
[inline](<https://somecompany.com>)

You can add a tool tip to the link to help users learn more about where the link will take them (to avoid click bait).

[have a title](<https://somecompany.com> "Awesome tooltip")
[like this](../blob/master/LICENSE.txt)

These are best for links that are used multiple times in an article, for example, the support link.

[1]: https://<domain>.com

<!-- usage -->
[Join our Slack community][1]

Output example

Join our Slack community

tip

You can add a tool tip to the link to help users learn more about where the link will take them (to avoid click bait).

[2]: https://<domain>.com "Beyond Identity Secure Workforce community"

<!-- usage -->
[Join the conversation][2]

Images​

Images can also be inline or use a reference style, like links, but with an exclamation point (!) at the front of the path.

Inline style​

This is the most common method for using images in an article once. If you’re using an image multiple times in the article, use the reference-style mentioned below.

![alt text](path to image) //inline-style

Reference style​

Use this method for articles that have the same image in multiple places. For example, an integration guide might mention a couple of different methods of doing something, and those methods have the same image. Therefore, you’d want to use the reference style to reuse images.

[logo]: https://<domain>.com/images/icon48.png "Logo Title Text 2"

<!-- Usage -->
![alt text][logo]
[![alt text](imageurl)](linkurl)

Other methods​

<img
  id="diagrams"
  src={require('../images/passkey-workflow-diagram.png').default}
  alt="Example banner"
/>
import AuthenticationRequestDiagram from '../images/passkey-workflow-diagram.png';

<img src={AuthenticationRequestDiagram} id="diagrams" alt="Example banner" />;

Lists​

Lists are made by using indentation and a beginning-of-line marker to indicate a list item.

Unordered lists​

Unordered lists can use an asterisk (*), plus (+), or minus (-) to indicate each list item.

* One item
* Second item
* Third item
* Fourth item
* Fifth item

Output example

  • One item
  • Second item
  • Third item
  • Fourth item
  • Fifth item

Don’t mix and match delimiters in the same list — pick one and stick with it.

✅ DO🚫 DON'T
* One item
* Second item
* Third item
* Fourth item
* Fifth item
* One item
+ Second item
- Third item
* Fourth item
+ Fifth item

Ordered lists​

Ordered lists use a number at the beginning of the line. The numbers do not need to be incremented - this will happen for you automatically by the HTML. That makes it easier to re-order your ordered lists (in markdown) as needed.

3. Step
2. Step
4. Step
1. Step

OR

1. Step
1. Step
1. Step
1. Step

Output example

  1. Step
  2. Step
  3. Step
  4. Step

Nested unordered lists​

Remember to pick a delimiter and stick with it.

* One item
* Another item
  * A sub-item
    * A deeper item
  * Back in sub-item land
* And back at the main level

Output example

  • One item
  • Another item
    • A sub-item
      • A deeper item
    • Back in sub-item land
  • And back at the main level

Nested ordered lists​

1. Step one
1. Step two
   1. Sub-step a
   1. Sub-step b
1. Step three
1. Step four
   1. Sub-step a
   1. Sub-step b
1. Step five

Output example

  1. Step one
  2. Step two
    1. Sub-step a
    2. Sub-step b
  3. Step three
  4. Step four
    1. Sub-step a
    2. Sub-step b
  5. Step five

Nested ordered and unordered lists​

You can use both types of lists to nest items. In the example below, the unordered list under the second ordered list item refers to items that aren’t sequential (no need to perform a task in a specified order).

* One item
* Another item
  1. A nested ordered list
  1. This is the second item
     * And now an unordered list as its child
     * Another item in this list
  1. One more in the ordered list
* And back at the main level

Output example

  • One item
  • Another item
    1. A nested ordered list
    2. This is the second item
      • And now an unordered list as its child
      • Another item in this list
    3. One more in the ordered list
  • And back at the main level

Line breaks​

For compatibility, use trailing white space (spacebar) or pressing Enter or Shift+Enter to add the line breaks manually. You can also use the <br> HTML tag at the end of the line.

Code and syntax highlighting​

Inline code​

Individual elements (words) within a line.

Here's an example of code style.

Use code format when referring to named parameters and variables in a nearby code block in your text. Code format may also be used for properties, methods, classes, and language keywords.

Use one backtick (`) around the code. This is the markdown version of the <code> tag in HTML.

Code blocks​

Use inline code blocks when it's impractical to display code by reference to a code file.

Use three backticks (<code>```</code>) with the language. This is the markdown version of the <pre\> tag in HTML.

  ```javascript
    module.exports = {
      sidebar: [
        {
          type: 'category',
          label: 'Overview',
          items: ['release-notes', 'intro', 'how-it-works'],
        };
      ],
    },
  ```

Output example

  module.exports = {
    sidebar: [
      {
        type: 'category',
        label: 'Overview',
        items: ['release-notes', 'intro', 'how-it-works'],
      };
    ],
  },

Tables​

The simplest way to create a table in Markdown is to use pipes and lines. To create a standard table with a header, follow the first line with dashed line:

|This is   |a simple   |table header|
|----------|-----------|------------|
|table     |data       |here        |
|it doesn't|actually   |have to line up nicely!|

Output example

This isa simpletable header
tabledatahere
it doesn'tactuallyhave to line up nicely!

You can align the columns by using colons:

| Fun                  | With                 | Tables          |
| :------------------- | -------------------: |:---------------:|
| left-aligned column  | right-aligned column | centered column |
| $100                 | $100                 | $100            |
| $10                  | $10                  | $10             |
| $1                   | $1                   | $1              |

Output example

FunWithTables
left-aligned columnright-aligned columncentered column
$100$100$100
$10$10$10
$1$1$1
tip

You can also use an online table generator.

Inconsistent column widths between tables​

You may notice that the column widths of the tables look odd or inconsistent. This behavior occurs because the length of text within the cells determines the layout of the table. Unfortunately, there's no way to control how the tables render. This is a limitation of Markdown. Even though it would look nicer to have the width of table columns be consistent, this would have some disadvantages too:

  • Interlacing HTML code with Markdown makes topics more complicated and discourages community contributions.
  • A table that you make look good for a specific screen size may end up looking unreadable at different screen sizes as it preempts responsive rendering.

Data matrix tables​

A data matrix table has both a header and a weighted first column, creating a matrix with an empty cell in the top left. Docs has custom Markdown for data matrix tables:

|                  |Header 1 |Header 2|
|------------------|---------|--------|
|**First column A**|Cell 1A  |Cell 2A |
|**First column B**|Cell 1B  |Cell 2B |

Output example

Header 1Header 2
First column ACell 1ACell 2A
First column BCell 1BCell 2B

Every entry in the first column must be styled as bold (**bold**); otherwise the tables won't be accessible for screen readers or valid for Docs.

Blockquotes​

Blockquotes are created using the > character:

> This is a blockquote. It is usually rendered indented and with a different background color.

Output example

This is a blockquote. It is usually rendered indented and with a different background color.

Indentation​

In Markdown, spaces before the first character of a line determine the line's alignment relative to the preceding lines. Indentation especially influences numbered and bulleted lists to render multiple levels of nesting in a hierarchical or outline format.

To indent text to align with a preceding paragraph or an item in a numbered or bulleted list, use spaces.

// Example 1
1. This is a numbered list example (one space after the period before the letter T).

   This sentence is indented three spaces.

   `This code block is indented three spaces.`

// Example 2
- This is a bulleted list example (one space after the bullet before the letter T).
  This sentence is indented two spaces.

// Example 3
- This is a second-level bullet (indented two spaces, with one space after the bullet before the letter T).
    This sentence is indented four spaces.
    > This quote block is indented four spaces.

Output of Example 1

  1. This is a numbered list example (one space after the period before the letter T).

    This sentence is indented three spaces.

    This code block is indented three spaces.

Output of Example 2

  • This is a bulleted list example (one space after the bullet before the letter T). This sentence is indented two spaces.

Output of Example 3

  • This is a second-level bullet (indented two spaces, with one space after the bullet before the letter T). This sentence is indented four spaces.

    This quote block is indented four spaces.

Docusaurus specific markdown​

Notes and warnings​

In addition to the basic Markdown syntax, we have a special admonitions syntax by wrapping text with a set of 3 colons, followed by a label denoting its type.

:::note

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::tip

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::info

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::caution

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::danger

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

Output example

note

Some content with Markdown syntax. Check this api.

tip

Some content with Markdown syntax. Check this api.

info

Some content with Markdown syntax. Check this api.

caution

Some content with Markdown syntax. Check this api.

danger

Some content with Markdown syntax. Check this api.

Highlighting codeblocks with comments​

  ```text title=".env.local"
  # -- Next Auth
  NEXTAUTH_URL=http://localhost:8083
  NEXTAUTH_SECRET= # Linux: `openssl rand -hex 32` or go to https://generate-secret.now.sh/32

  # -- Beyond Identity
  // highlight-next-line
  REGION=

  TENANT_ID=
  REALM_ID=
  API_TOKEN=

  APPLICATION_ID=
  AUTHENTICATOR_CONFIG_ID=

  APP_CLIENT_ID=
  APP_CLIENT_SECRET=
  ```

Output example

.env.local
# -- Next Auth
NEXTAUTH_URL=http://localhost:8083
NEXTAUTH_SECRET= # Linux: `openssl rand -hex 32` or go to https://generate-secret.now.sh/32

# -- Beyond Identity
REGION=

TENANT_ID=
REALM_ID=
API_TOKEN=

APPLICATION_ID=
AUTHENTICATOR_CONFIG_ID=

APP_CLIENT_ID=
APP_CLIENT_SECRET=

Tabs​

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="apple" label="Apple" default>
    This is an apple 🍎
  </TabItem>
  <TabItem value="orange" label="Orange">
    This is an orange 🍊
  </TabItem>
  <TabItem value="banana" label="Banana">
    This is a banana 🍌
  </TabItem>
</Tabs>

Output example

This is an apple 🍎

Details​

Markdown can embed HTML elements, and details HTML elements are beautifully styled:

<details className="detailsContainer">
  <summary className="summaryHeading">Toggle me!</summary>
  <div>
    <p>This is the detailed content</p>
    <br/>
    <details>
      <summary>
        Nested toggle! Some surprise inside...
      </summary>
      <div>😲😲😲😲😲</div>
    </details>
  </div>
</details>

Output example

Toggle me!

This is the detailed content


Nested toggle! Some surprise inside...

😲😲😲😲😲