---
id: writing-docs
title: Writing Docs
---

Documentation is one of your product's interfaces with your users. A well-written and well-organized set of docs helps your users understand your product quickly. Our aligned goal here is to help your users find and understand the information they need, as easily as possible.

Docusaurus 2 uses modern tooling to help you compose your interactive documentations with ease. You may embed React components, or build live coding blocks where your users may play with the code on the spot. Start sharing your eureka moments with the code your audience cannot walk away from. It is perhaps the most effective way of attracting potential users.

In this section, we'd like to introduce you to the tools we've picked that we believe will help you build powerful documentation. Let us walk you through with an example.

**Note:** All the following content assumes you are using `docusaurus-preset-classic`.

## Using Markdown

Markdown is a syntax that enables you to write formatted content in an easy-to-use syntax. The [standard Markdown syntax](https://daringfireball.net/projects/markdown/syntax) is supported and we use [MDX](https://mdxjs.com/) as the parsing engine, which can do much more than just parsing Markdown. More on that later.

Create a markdown file, `greeting.md`, and place it under the `docs` directory of your website's root.

```bash
website # root directory of your site
├── docs
│   └── greeting.md
├── pages
├── docusaurus.config.js
├── ...
```

<!-- TODO: talk about where to put the docs, resolving docs outside of website directory, etc. -->

In the beginning of this file, specify `id` the `title` in the front matter, so that Docusaurus will pick them up correctly when generating your site.

```markdown
---
id: greeting
title: Hello
---

## Hello from Docusaurus

Are you ready to create the documentation site for your open source project?

### Headers

will show up on the table of contents on the upper right

So that your users will know what this page is all about without scrolling down or even without reading too much.

### Only h2 and h3 will be in the toc

The headers are well-spaced so that the hierarchy is clear.

- lists will help you
- present the key points
- that you want your users to remember
  - and you may nest them
    - multiple times
```

This will render in the browser as follows:

import BrowserWindow from '../components/BrowserWindow';

<BrowserWindow url="http://localhost:3000">
<h2>Hello from Docusaurus</h2>

Are you ready to create the documentation site for your open source project?

<h3>Headers</h3>

will show up on the table of contents on the upper right

So that your users will know what this page is all about without scrolling down or even without reading too much.

<h3>Only h2 and h3 will be in the toc</h3>

The headers are well-spaced so that the hierarchy is clear.

- lists will help you
- present the key points
- that you want your users to remember
  - and you may nest them
    - multiple times

</BrowserWindow>

## Sidebar

To generate a sidebar to your Docusaurus site, you need to define a file that exports a JS module and pass that into `docusaurus-plugin-docs` directly or via the `docusaurus-preset-classic`. If you are using the classic preset, you can find the `sidebars.js` under the root directory already created for you, so you may edit it directly for customization.

<!-- TODO: change classic template to use `sidebars.js` from json -->

```bash
website # root directory of your site
├── docs
│   └── greeting.md
├── docusaurus.config.js
├── sidebars.js
.
```

To add a doc to the sidebar, add the `id` specified in the frontmatter of the doc into its category.

```diff
module.exports = {
  docs: {
+   "Getting started": ["greeting"],
    "Docusaurus": ["doc1"],
    "First Category": ["doc2"],
    "Second Category": ["doc3"],
  }
};
```

The `docs` key in the file is just the name of that particular sidebar hierarchy, and can be renamed to something else. You can have multiple sidebars for different Markdown files by adding more top-level keys to the exported object.

<!-- TODO: Mention subcategories -->

<!--
TODO: Talk more about using the official docs plugin and how to configure the sidebar. Mention about incorporating assets and a preview of the cool Markdown features available, but don't list all the Markdown features here.
References:
- https://docusaurus.io/docs/en/navigation
-->

## Embedding React Components

Docusaurus has built-in support for [MDX](https://mdxjs.com), which allows you to write JSX within your Markdown files and render them as React components.

**Note:** While both `.md` and `.mdx` files are parsed using MDX, some of the syntax are treated slightly differently. For the most accurate parsing and better editor support, we recommend using the `.mdx` extension for files containing MDX syntax. Let's rename the previous file to `greeting.mdx`

Try this block here:

```jsx
export const Highlight = ({children, color}) => (
  <span
    style={{
      backgroundColor: color,
      borderRadius: '2px',
      color: '#fff',
      padding: '0.2rem',
    }}>
    {children}
  </span>
);

<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.

I can write **Markdown** alongside my _JSX_!
```

Notice how it renders both the markup from your React component and the Markdown syntax:

export const Highlight = ({children, color}) => (
  <span
    style={{
      backgroundColor: color,
      borderRadius: '2px',
      color: '#fff',
      padding: '0.2rem',
    }}>
    {children}
  </span>
);

<BrowserWindow minHeight={240} url="http://localhost:3000">
<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.

I can write **Markdown** alongside my _JSX_!

</BrowserWindow>

<br />

You can also import your own components defined in other files or third-party components installed via npm! Check out the [MDX docs](https://mdxjs.com/) to see what other fancy stuff you can do with MDX.

## Syntax Highlighting

Code blocks are text blocks wrapped around by strings of 3 backticks. You may check out [this reference](https://github.com/mdx-js/specification) for specifications of MDX.

    ```jsx
    console.log('Every repo must come with a mascot.');
    ```

<!-- TODO: We need to allow users to pick syntax highlighting themes (maybe other than swizzling) -->

Use the matching language meta string for your code block, and Docusaurus will pick up syntax highlighting automatically, powered by [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer). Just in case you need it, [here](https://prismjs.com/#supported-languages) is a list of supported languages and their corresponding meta strings.

```jsx
console.log('Every repo must come with a mascot.');
```

**Work in Progress** Currently the Prism theme we use is [Night Owl](https://github.com/FormidableLabs/prism-react-renderer/blob/master/themes/nightOwl.js). We will support customized theme in a future version.

## Interactive Coding Editor

(Powered by [React Live](https://github.com/FormidableLabs/react-live))

You can create an interactive coding editor with the `@docusaurus/theme-live-codeblock` plugin.

First, add the plugin to your package.

```bash
npm i @docusaurus/theme-live-codeblock
```

You will also need to add the plugin to your `docusaurus.config.js`.

```diff
module.exports = {
  ...
+ themes: ['@docusaurus/theme-live-codeblock'],
  ...
}
```

To use the plugin, create a code block with `live` attached to the language meta string.

    ```jsx live
    function Clock(props) {
      const [date, setDate] = useState(new Date());
      useEffect(() => {
        var timerID = setInterval(() => tick(), 1000);

        return function cleanup() {
          clearInterval(timerID);
        };
      });

      function tick() {
        setDate(new Date());
      }

      return (
        <div>
          <h2>It is {date.toLocaleTimeString()}.</h2>
        </div>
      );
    }
    ```

The code block will be rendered as an interactive editor. Changes to the code will reflect on the result panel live.

```jsx live
function Clock(props) {
  const [date, setDate] = useState(new Date());
  useEffect(() => {
    var timerID = setInterval(() => tick(), 1000);

    return function cleanup() {
      clearInterval(timerID);
    };
  });

  function tick() {
    setDate(new Date());
  }

  return (
    <div>
      <h2>It is {date.toLocaleTimeString()}.</h2>
    </div>
  );
}
```

**Note** The React Live component is rather big in bundle size. It is an opt-in.