Basic Formatting

Syntax

Format	Syntax
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.

# This is a first level heading (H1)

## This is a second level heading (H2)

...

###### This is a sixth level heading (H6)

Formatting guidelines

Always put a space between the hash tag and the heading name. Also, put blank lines before and after a heading.
Correct
# Here's a Heading
Put a extra space (blank line) before...
# Heading
...and after a heading.
Incorrect
#Here's a Heading
No space (blank line) before...
# Heading
...and after a heading.
Maintain consistent punctuation, generally avoiding periods and colons.

Writing style

Be concise and descriptive
Use action-oriented language
Avoid articles (a, an, the) at the beginning
Keep headings under 65 characters
Use sentence case for headings and title case for the document title

Make headings scannable

Front-load important keywords
Use descriptive terms instead of generic ones
Avoid abbreviations unless widely known
Make headings unique within the document

Links

Basic links

[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")

Relative links

[like this](../blob/master/LICENSE.txt)

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

Example

![alt text](https://<domain>.com/images/icon48.png "Logo Title Text 1")

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]

Images with links

[![alt text](imageurl)](linkurl)

This method automatically reduces the image by 60% and adds a border around the image. You can zoom in on the image to see the details.

Other methods

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

JavaScript
import AuthenticationRequestDiagram from './images/passkey-workflow-diagram.png';

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

JavaScript
import AuthenticationRequestDiagram from './images/passkey-workflow-diagram.png';

<AuthenticationRequestDiagram />

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 (*) or minus (-) to indicate each list item.

- One item
- Second item
- Third item
- Fourth item
- Fifth item

Output

One item
Second item
Third item
Fourth item
Fifth item

important

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

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.

Step
Step
Step
Step

Step
Step
Step
Step

Output

Step
Step
Step
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

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

Nested ordered lists

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

Output

Step one
Step two
1. Sub-step a
2. Sub-step b
Step three
Step four
1. Sub-step a
2. Sub-step b
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

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 (```) with the language. This is the markdown version of the <pre> tag in HTML.

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

The example renders as:

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

Highlighting codeblocks with comments

You can use comments with highlight-next-line, highlight-start, and highlight-end to select which lines are highlighted.

```jsx
function HighlightSomeText(highlight) {
  if (highlight) {
    // highlight-next-line
    return 'This text is highlighted!';
  }

  return 'Nothing highlighted';
}

function HighlightMoreText(highlight) {
  // highlight-start
  if (highlight) {
    return 'This range is highlighted!';
  }
  // highlight-end

  return 'Nothing highlighted';
}
```

function HighlightSomeText(highlight) {
  if (highlight) {
    return 'This text is highlighted!';
  }

  return 'Nothing highlighted';
}

function HighlightMoreText(highlight) {
  if (highlight) {
    return 'This range is highlighted!';
  }

  return 'Nothing highlighted';
}

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!|

This renders as follows:

This is	a simple	table header
table	data	here
it doesn't	actually	have 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              |

Renders as follows:

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

tip

You can also use an online table generator.

Inconsistent column widths

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 |

The example renders as:

	Header 1	Header 2
First column A	Cell 1A	Cell 2A
First column B	Cell 1B	Cell 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

Avoid using. Use the Admonitions instead.

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 four 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 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 four spaces.
```

Example 2

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

Syntax

Headings

Formatting guidelines

Correct

Incorrect

Writing style

Make headings scannable

Links

Basic links

Link with tooltip

Relative links

Images

Inline style

Reference style

Images with links

Other methods

Lists

Unordered lists

Ordered lists

Nested unordered lists

Nested ordered lists

Nested ordered and unordered lists

Line breaks

Code and syntax highlighting

Inline code

Code blocks

Highlighting codeblocks with comments

Tables

Inconsistent column widths

Data matrix tables

Blockquotes

Indentation