Skip to main content

Markdown writing guide

This guide has basic information on how to write in MDX-compatible Markdown syntax. It is not intended to be exhaustive. Read the Docusaurus Markdown features, Basic Markdown Syntax, and Extended Syntax for more details and examples.

File format and naming convention​

When creating new files, keep the filename short. Don't use capital letters or spaces. When the filename of a Markdown file matches the name of a folder exactly, clicking the folder displays the contents of the Markdown file.

A Markdown file can have either an .md or .mdx extension but you can override the MD format with the front matter format: mdx. When choosing between the MD and MDX formats, use the MDX format only if you are using JSX. The MDX format is strict, and you may get compilation errors.

By default, documents and folders displayed on the left sidebar are sorted alphabetically. You can specify custom labels and order:

  • For documents, use the sidebar_position and sidebar_label front matter:

    sidebar_position: 1
    sidebar_label: 'Custom document title'

  • For folders, create a _category_.yml file within a folder and specify the position and label front matter in that file:

    position: 1 # float position is supported
    label: 'Custom folder title'

Metadata (front matter)​

Markdown documents have metadata at the top called front matter. At the very top of each wiki page, include the following:

Parameter/TypeDescription
title (string)Required. The title is automatically rendered using the H1 style at the top of the page and is used in navigation if a sidebar_label is not included. Keep it short (1-3 words).
sidebar_label (string)Optional. Use a different title for the left sidebar navigation.
sidebar_position (number)Optional. Overrides default position of a doc inside the sidebar directory.
description (string)Optional. This is what appears when the page is referenced in a Google search result.
keywords (string[ ])Optional. A list of meta tags for the document page and search engines.

To see the full list of available options, visit the Docusaurus website.

Introduction​

In the first paragraph of the document, provide an overview of the topic and/or set the user's expectation for what they will find on this page.

Table of contents. Headers​

  • For titles and headers, use Sentence case like this. This means only capitalizing the first word and any proper nouns.

  • Don't end headers with a period.

  • Don't include your own table of contents (TOC). Both GitHub and Docusaurus automatically generate TOC based on the document's headers.

  • H1 headers: Never use in a document. The title front matter is automatically generated as an H1.

  • H2 headers: These headers are shown in the page's TOC. Ensure they concisely reflect the content of each section. Keep it short (1-3 words).

  • H3 headers: These headers are also shown in the TOC. Ensure the headers represent the content that users may want to access directly. Keep it short (1-3 words).

  • H4 headers: These headers emphasize things within a subsection of the page. They can be longer than the other headers because they aren't shown in the TOC.

Content​

Tabs are a great option for providing context-driven information. For example, you can use tabs to show code examples in different languages or instructions for different operating systems.

To use tabs, add these lines right below the front matter:

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

For each set of tabs, use this code:

 <Tabs groupID="my-group"
    defaultValue="alpha"
    values={[
      {label: 'Alpha', value: 'alpha'},
      {label: 'Beta', value: 'beta'},
    ]}>
  <TabItem value="alpha">Text for alpha.</TabItem>
 <TabItem value="beta">Text for beta.</TabItem>
 </Tabs>

To synchronize tabs of the same kind, assign a groupId parameter to all related tabs. This ensures that the chosen selection persists across all instances of tabs with the same groupId.

Example
 <Tabs groupId="operating-systems">
 <TabItem value="windows" label="Windows">Windows instructions.</TabItem>
 <TabItem value="linux" label="Linux">Linux instructions.</TabItem>
 </Tabs>

 <Tabs groupId="operating-systems">
 <TabItem value="windows" label="Windows">More Windows instructions.</TabItem>
 <TabItem value="linux" label="Linux">More Linux instructions.</TabItem>
 </Tabs>

Troubleshooting​

A common issue with Docusaurus is the sensitivity of MDX to the placement of code blocks and other text. If you've included a code block or text using common markdown syntax, and things aren't rendering as expected, try the following:

  • Add an empty line after above and below each code block or text.

  • When dealing with tabs, either indent the code by five spaces or wrap the MDX tags in an mdx-code-block:

         ```mdx-code-block
         <Tabs>
         <TabItem value="tab" label="Tab">
         ```
      
         Tab contents.

         ```mdx-code-block
         </TabItem>
         </Tabs>
         ```