How to Create and Deploy a Documentation Website With Docusaurus and Netlify

Originally Posted on My Personal Blog.

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

To deploy your docusaurus website, you'll need a GitHub and Netlify 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.

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.

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.

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.

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.

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".

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.

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.

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.

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

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.

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

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

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.

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.

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.

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".

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.

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.

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

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.

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.
2. Learn how to manage your documentation's pages and blog.
3. Check out Docusaurus's documentation to learn about all the features you can add to your documentation.