docusaurus/website/docs/writing-documentation.md

id	title
writing-documentation	Writing Documentation

Next, let's touch on the powerful feature in Docusaurus - documentation.

Using Markdown

Create a new file within the docs directory called hello.md with the following contents:

---
title: Hello
---

I can write content using [GitHub-flavored Markdown syntax](https://github.github.com/gfm/).

## Markdown Syntax

**Bold** _italic_ `code` [Links](#url)

> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

- Hey
- Ho
- Let's Go

Docusaurus supports Markdown syntax using Remark for Markdown parser and is extensible via plugins.

Embedding React Components

Did you know that you can now write React components within your Markdown files? This is possible because of MDX, which allows you to write JSX within your Markdown documents.

Now we'll add a third-party chart component into the Markdown file created above. Before that, kill your web server (Cmd + C or Ctrl + C) if it's running and install react-trend in your website directory.

npm install react-trend

Start the development server again and go to http://localhost:3000/docs/hello, you will see a new page created from the Markdown file.

Edit docs/hello.md and append the following:

import Trend from 'react-trend';

_Here's a bar chart!_

<Trend
  smooth
  autoDraw
  autoDrawDuration={3000}
  autoDrawEasing="ease-out"
  data={[0, 2, 5, 9, 5, 10, 3, 5, 0, 0, 1, 8, 2, 9, 0]}
  gradient={['#00c6ff', '#F0F', '#FF0']}
  radius={10}
  strokeWidth={2}
  strokeLinecap={'butt'}
/>

Save the file and notice that the site is hot-reloaded with the edited content.

We just imported a React component and embedded it within our markdown 😉!

Sidebar

Next, let's add this page to the sidebar.

Edit the sidebars.json file and add the hello document.

{
  "docs": {
+   "Getting started": ["hello"],
    "Docusaurus": ["doc1"],
    "First Category": ["doc2"],
    "Second Category": ["doc3"]
  },
  "docs-other": {
    "First Category": ["doc4", "doc5"]
  }
}

You can see that there is a sidebar now on http://localhost:3000/docs/hello.

Syntax highlighting

If you're writing technical documentation you may want a way to delineate blocks of code, sometimes known as a code fence. The result is also known as a code block. The simplest way to show code is to wrap it between two lines consisting of 3 backticks in a row.

Example:

```jsx
  console.log("Hello world");
```

And the result would be:

console.log("Hello world");

Live Editor

You can also create live code editors with a code block live meta string.

Example:

```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>
  );
}
```

And the result would be:

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>
  );
}