How to Create and Deploy a Documentation Website With Docusaurus and Netlify
Tags: javascript, webdev, programming, hosting
Published: 2022-05-18 11:50:02

---
title: How to Create and Deploy a Documentation Website With Docusaurus and Netlify
published: true
date: 2022-05-16 10:29:16 UTC
tags: javascript, webdev, programming, hosting
canonical_url: https://blog.shahednasser.com/how-to-create-and-deploy-a-documentation-website-with-docusaurus-and-netlify/
cover_image: https://blog.shahednasser.com/static/4bceefeacc54e38721d0491696b87d19/How-to-Create-and-Deploy-a-Documentation-Website-With-Docusaurus-and-Netlify.jpg
---

_Originally Posted on [My Personal Blog](https://blog.shahednasser.com/how-to-create-and-deploy-a-documentation-website-with-docusaurus-and-netlify/)._

Documentation websites are used to help people learn about your product or solution. More specifically for developers, it's an important resource to help other developers learn more about your tool and understand better how to use it.

In this tutorial, you'll learn how to create documentation with [Docusaurus](https://docusaurus.io). This documentation website will have features such as multi-language code blocks and local search. You'll then deploy the website with Netlify.

## Prerequisites

Docusaurus requires Node.js version 14.3 or above. If you don't have Node.js installed you can install it from [their website](https://nodejs.org/en/).

To deploy your docusaurus website, you'll need a [GitHub](https://github.com) and [Netlify](https://www.netlify.com) accounts. You must also have an empty repository to hold the code of your docusaurus website.

## Project Installation

Start by creating a new Docusaurus project with the following command:

```
npx create-docusaurus@latest my-docs classic
```

This will install Docusaurus in the directory `my-docs` and it will use the `classic` template.

Now, change to the directory `my-docs` and start the Docusaurus server:

```
cd my-docs
npm start
```

This will start the server on `localhost:3000` and should open the website automatically in your browser.

![How to Create and Deploy a Documentation Website With Docusaurus and Netlify](https://backend.shahednasser.com/content/images/2022/05/Screen-Shot-2022-05-14-at-2.29.50-PM.png)

The code for the landing page is in `src/pages/index.js`. However, this tutorial only focuses on the documentation part.

To open the documentation, click on Tutorial in the Navigation bar. You'll see a few documentation pages created by default with Docusaursus.

![How to Create and Deploy a Documentation Website With Docusaurus and Netlify](https://backend.shahednasser.com/content/images/2022/05/Screen-Shot-2022-05-14-at-2.30.00-PM.png)

Documentation pages reside in the `docs` directory of your docusaurus project. They are either MD or MDX files. MD files are basic Markdown files with Markdown syntax. MDX files are Markdown files that also support React syntax within.

![How to Create and Deploy a Documentation Website With Docusaurus and Netlify](https://backend.shahednasser.com/content/images/2022/05/Screen-Shot-2022-05-14-at-2.30.16-PM.png)

Try to change the content of `intro.md` to the following:

```
---
sidebar_position: 1
---

# Introduction

I've changed the documentation!
```

If the server is still running and you go back to the website, you'll see that the content of the page has changed.

![How to Create and Deploy a Documentation Website With Docusaurus and Netlify](https://backend.shahednasser.com/content/images/2022/05/Screen-Shot-2022-05-14-at-2.31.08-PM.png)

Notice that there are at the top of the markdown file three dashes followed by some key-value properties, then followed again by 3 dashes. These are Markdown front matter fields that provide customization to some meta data attributes of the document such as the page title or, in this case, its position in the sidebar.

## Create a New Document

To create a new document, you need to create a new file under the `docs` directory.

In this section, you'll create an MDX file to showcase and add some MDX features later in this tutorial.

Create `tabs.mdx` with the following content:

```
# How to Use Tabs
```

This will add a heading to the page. If you check your documentation website, you should find a new link in the sidebar for the new page.

![How to Create and Deploy a Documentation Website With Docusaurus and Netlify](https://backend.shahednasser.com/content/images/2022/05/Screen-Shot-2022-05-14-at-2.33.25-PM.png)

Let's rearrange the position of the link in the sidebar. Add the following at the top of `tabs.mdx`:

```
---
sidebar_position: 2
---
```

This will move "How to Use Tabs" right after "Introduction".

![How to Create and Deploy a Documentation Website With Docusaurus and Netlify](https://backend.shahednasser.com/content/images/2022/05/Screen-Shot-2022-05-14-at-3.32.43-PM.png)

## Optional Features

This section includes optional features you can make use of in your documentation. You can skip this section or any subsection if you don't find them necessary for you.

### Use Tabs

Using MDX provides you with a lot of features in your Markdown files. One of those features is adding tabs to your page.

In `tabs.mdx` add the following after the frontmatter part you added earlier:

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

Then, after the heading of the page, add the following to add tabs to the page:

```
<Tabs groupId="tabs">
  <TabItem value="tab1" label="Tab 1" default>
    I like tab 1
  </TabItem>
  <TabItem value="tab2" label="Tab 2">
    I like tab 2
  </TabItem>
</Tabs>
```

This will add 2 tabs with each having different text. Notice the following:

1. The `groupId` prop on `Tabs` allows you to synchronize the choice of tab throughout the website.
2. Each tab item must have a `value` prop. If you want to synchronize the choice of tab throughout the website, you'll need to use the same value for tabs used in other locations (you'll see an example in a bit).
3. The `default` prop makes a tab selected by default when the page is first opened.

Open the documentation now and you'll see tabs added to the documentation. You can click between the tabs and the text will change.

![How to Create and Deploy a Documentation Website With Docusaurus and Netlify](https://backend.shahednasser.com/content/images/2022/05/Screen-Shot-2022-05-14-at-3.36.34-PM.png)

Let's try adding another `Tab` component under the previous one:

```
<Tabs groupId="tabs">
  <TabItem value="tab1" label="Tab 1" default>
    I still like tab 1
  </TabItem>
  <TabItem value="tab2" label="Tab 2">
    I still like tab 2
  </TabItem>
</Tabs>
```

Notice that `Tabs` has the same `groupId` as the previous `Tabs` element, and the tab items have the same values as well.

If you open the website now you'll see two tabs components each with tab items and text. Try choosing a tab from either component and the choice will be synced with the other tab component as well.

![How to Create and Deploy a Documentation Website With Docusaurus and Netlify](https://backend.shahednasser.com/content/images/2022/05/ezgif.com-gif-maker-2.gif)

### Multi-Language Code Blocks

You can also utilize tabs to add code blocks with multiple languages. This is helpful if you want to show the same code block in multiple languages.

Below the previous tabs you added add this new tab component:

```
<Tabs groupId="code-tabs">
  <TabItem value="js" label="JavaScript" default>

  ```js
  console.log("Hello")
  ```
  
  </TabItem>
  <TabItem value="python" label="Python">

  ```py
  print("Hello")
  ```

  </TabItem>
</Tabs>
```

Notice the following:

- This `Tabs` component has a different value for `groupId` compared to previous tabs. That's because there's no need for synchronization between this `Tabs` component and previous components.
- The code blocks inside tabs must be surrounded by empty lines. Otherwise, they will not be rendered properly.
- The indentation for the code blocks should not be more than one tab (equivalent to 2 spaces) or it might not render properly.

If you open the website now, you'll see tabs for the code blocks.

![How to Create and Deploy a Documentation Website With Docusaurus and Netlify](https://backend.shahednasser.com/content/images/2022/05/Screen-Shot-2022-05-14-at-2.36.12-PM.png)

### Add Automatic NPM and Yarn Tabs

NPM and Yarn are common package managers used for Node.js-related projects and tools. A lot of times, you want to show the same command in both NPM and Yarn. However, it's a hassle to manually add tabs each time you want to do it.

In this case, you can make use of the [npm2yarn remark plugin](https://docusaurus.io/docs/markdown-features/code-blocks#npm2yarn-remark-plugin). This plugin will allow you to automatically convert all code blocks that use NPM to yarn on your documentation.

Start by installing the npm2yarn plugin:

```
npm install @docusaurus/remark-plugin-npm2yarn
```

Then, in `docusarus.config.js` you need to add a new option `remarkPlugins` in the `config` object:

```
const config = {
	//other options...
    presets: [
        [
          'classic',
          /** @type {import('@docusaurus/preset-classic').Options} */
          ({
              docs: {
                  //other options...
                  remarkPlugins: [
                    [require('@docusaurus/remark-plugin-npm2yarn'), {sync: true}],
          ],
              }
          })
        ]
    ]
};
```

The `{sync: true}` option enables synchronizing the user's choice of tab across the website, similar to the behavior you saw earlier with Tabs.

Now, in `tabs.mdx` add the following at the end:

```
```bash npm2yarn
npm install react
```
```

The important bit here is `npm2yarn`. If you want a code block to have "npm" and "Yarn" tabs and you want to convert the command to yarn, add this keyword after the first 3 backticks of your code block.

Start your server again and open the website now on the "How to Use Tabs" documentation page. You might need to perform a hard refresh to clear your website's cache.

If you scroll down you should see the code block you added but with 2 tabs "npm" and "Yarn". You'll also see that the command was automatically converted to a Yarn command under the Yarn tab.

![How to Create and Deploy a Documentation Website With Docusaurus and Netlify](https://backend.shahednasser.com/content/images/2022/05/Screen-Shot-2022-05-14-at-2.57.37-PM.png)

### Table of Content

The last feature you'll learn about in MDX files is the table of content. You can automatically generate a table of content for any page.

In `tabs.mdx` under the previous imports add a new import:

```
import TOCInline from '@theme/TOCInline';
```

Then, add the following under the heading of the page:

```
<TOCInline toc={toc} />

## Heading 2
### Heading 3
```

If you open the website now, you'll see an automatically generated table of content under the header on the "How to Use Tabs" page.

![How to Create and Deploy a Documentation Website With Docusaurus and Netlify](https://backend.shahednasser.com/content/images/2022/05/Screen-Shot-2022-05-14-at-3.26.58-PM.png)

Note that the `TOCInline` component will only render headings starting from `h2` or `##`. It will not render `h1` or `#` headings.

## Add Search

An important functionality in any documentation is a search engine. In Docusaurus, you can utilize services like [Algolia](https://docusaurus.io/docs/search#using-algolia-docsearch) to add a search engine. However, in this tutorial, you'll add a local search engine that works well for small documentation.

In your terminal, run the following command to install the plugin:

```
npm install --save @easyops-cn/docusaurus-search-local
```

Then, in `docusaurus.config.js` add to the `config` object a new key `themes`:

```
themes: [
    [
      require.resolve("@easyops-cn/docusaurus-search-local"),
      {
        hashed: true,
      },
    ],
  ],
```

That's all you need to add a local search engine.

The search engine will not work if you use `npm start`. You first need to build the website:

```
npm run build
```

Then serve the build:

```
npm run serve
```

Open the website again at `localhost:3000`. You should see a search bar at the right of your navigation bar.

![How to Create and Deploy a Documentation Website With Docusaurus and Netlify](https://backend.shahednasser.com/content/images/2022/05/Screen-Shot-2022-05-14-at-3.04.56-PM.png)

Try searching for one of the pages you added and you should see the results in the dropdown.

![How to Create and Deploy a Documentation Website With Docusaurus and Netlify](https://backend.shahednasser.com/content/images/2022/05/Screen-Shot-2022-05-14-at-3.06.07-PM.png)

## Customize Sidebar

The sidebar at the moment is automatically generated from the files in the `docs` directory. You can, however, manually set the sidebar and items in it.

To do that, open `sidebars.js` and change the value of the `sidebars` object to the following:

```
const sidebars = {
   tutorialSidebar: [
        {
          type: 'doc',
          id: 'intro'
        },
        {
          type: 'category',
          label: 'Tutorial',
          items: [{
            type: 'doc',
            id: 'tabs',
            label: 'Learn all about tabs'
          }],
		}
	]
};
```

This will change the sidebar to include a link and a collapsable section with one sub-item.

If you open the website now you should see the sidebar changed.

![How to Create and Deploy a Documentation Website With Docusaurus and Netlify](https://backend.shahednasser.com/content/images/2022/05/Screen-Shot-2022-05-14-at-3.16.52-PM.png)

## Change the "Edit this page" Link

At the end of every document, you'll find an "Edit this page" link. This allows contributors to easily make changes they find necessary and submit a PR to your repository.

![How to Create and Deploy a Documentation Website With Docusaurus and Netlify](https://backend.shahednasser.com/content/images/2022/05/Screen-Shot-2022-05-14-at-4.03.29-PM.png)

The prefix URL of this page is set in `docusaurus.config.js` under the `docs` object in the `presets` array in the `config` object:

```
docs: {
	editUrl: 'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
	},
```

You should change that to your repository's `docs` directory. For example:

```
"https://github.com/shahednasser/docusaurus-tutorial/tree/master/"
```

The URL prefix should be the URL before reaching the `docs` directory.

You can test this out by committing and pushing your changes to the repository. Then, try clicking the link on any of the documents and a new page will open. It will be the document on GitHub where you can edit it and submit a PR with the changes.

![How to Create and Deploy a Documentation Website With Docusaurus and Netlify](https://backend.shahednasser.com/content/images/2022/05/Screen-Shot-2022-05-14-at-4.08.39-PM.png)

## Deploy Your Documentation Website

The last step you'll do is deploy the documentation website. Log in to Netlify, then click on "Add new site" and from the dropdown select "Import an existing project".

![How to Create and Deploy a Documentation Website With Docusaurus and Netlify](https://backend.shahednasser.com/content/images/2022/05/Screen-Shot-2022-05-14-at-4.10.21-PM.png)

A new page will open to create a new site. You can choose to import the code from multiple websites including GitHub. Click on GitHub.

![How to Create and Deploy a Documentation Website With Docusaurus and Netlify](https://backend.shahednasser.com/content/images/2022/05/Screen-Shot-2022-05-14-at-3.08.41-PM.png)

You'll then be asked to give Netlify permissions to your GitHub account if you haven't done that before.

After you give the necessary permissions, you'll be able to select a repository to deploy. Choose the repository you created for the docusaurus website.

![How to Create and Deploy a Documentation Website With Docusaurus and Netlify](https://backend.shahednasser.com/content/images/2022/05/Screen-Shot-2022-05-14-at-3.09.04-PM.png)

On the next page, Netlify will show build and deploy settings. They should be similar to the following:

![How to Create and Deploy a Documentation Website With Docusaurus and Netlify](https://backend.shahednasser.com/content/images/2022/05/Screen-Shot-2022-05-14-at-4.13.30-PM.png)

If all looks good, click on "Deploy site". Netlify will then build and deploy your site which will take a couple of minutes.

Once the deployment is done and published, you can access the website from the randomly generated domain name. You can find it at the top of your website's dashboard on Netlify.

![How to Create and Deploy a Documentation Website With Docusaurus and Netlify](https://backend.shahednasser.com/content/images/2022/05/Screen-Shot-2022-05-14-at-4.14.42-PM.png)

If you open your website you'll find that it's exactly similar to what you worked on locally with all features working well.

## Conclusion

In this tutorial, you learned about the different features of Docusaurus documentation, how to add local search, and how to deploy the website on Netlify.

There's still more to be done with your documentation. Here are some additional steps you can take:

1. Learn how to [customize your domain name in Netlify](https://docs.netlify.com/domains-https/custom-domains/).
2. Learn how to manage your documentation's [pages](https://docusaurus.io/docs/creating-pages) and [blog](https://docusaurus.io/docs/blog).
3. Check out [Docusaurus's documentation](https://docusaurus.io/docs/category/guides) to learn about all the features you can add to your documentation.