Set up and Customize a Documentation Site with Docusaurus

9 min readJun 12, 2024

Docusaurus is an open-source project developed by Meta (formerly Facebook) that simplifies the process of building, deploying, and maintaining documentation websites.

For technical writers, knowing how to set up Docusaurus is particularly important. You might need to build a documentation site from scratch or use Docusaurus as the default tool in your company. Proficiency with Docusaurus ensures you can create organized and user-friendly documentation.

Prerequisites

Have NodeJS and NPM installed on your computer.
A code editor. This tutorial uses VS code.
Basic understanding of ReactJS. Docusaurus is built on React, and having some experience with it can help you customize the website’s look and functionality further.
Knowledge of Markdown. Docusaurus uses Markdown for writing documentation.

Installation

To start the installation process, run the following command. This will create a scaffold project with the Docusaurus classic theme. You can replace docs-site with the name of your project.”

npx create-docusaurus@latest docs-site classic

Navigate to Your Project Directory

Change your directory to the newly created Docusaurus site.

cd docs-site

Launching the development server

Run the command below to launch a local development server where you can see your website. The default port is http://localhost:3000.

npx docusaurus start
or 
npm start

This command will start a local server and open your new Docusaurus site in your default web browser. You can view it at http://localhost:3000.

Customizing Your Site

This is a skeletal illustration of a Docusaurus file structure:

my-docs-site/
├── docs/
│   ├── doc1.md
│   ├── doc2.md
│   └── doc3/
│       └── doc3a.md
├── blog/
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2020-06-15-new-post.md
├── src/
│   ├── components/
│   │   └── MyComponent.js
│   └── pages/
│       └── index.js
├── static/
│   ├── img/
│   │   └── logo.png
│   └── css/
│       └── custom.css
├── docusaurus.config.js
├── sidebars.js
├── package.json
└── README.md

To begin customization on your site, here are some files and directories you should focus on:

.docusaurus.config.js: this file is the main configuration file for your Docusaurus site. You can set the Site title, tagline, URL Navigation bar, and footer links in it.
/docs: this directory contains your documentation files. Each Markdown file represents a separate documentation page.
src/pages/index.js: this file is your site's homepage. You can customize it to create a personalized landing page for your documentation.

Footer Customization

Navigate to your .docusaurus.config.js and find the footer section. There’s a template already, and you can further edit it to fit your needs.
This is what the demo customization looks like:

Navbar Customization

Still in your .docusaurus.config.js file, find the Navbar section, and start making edits.

image: that's the visual representation of your website's appearance when shared on social media.
title: this is the title of your documentation site.
logo: add the logo to your site and also the alt text.
items: this represents the element that will appear in the navigation bar (navbar). Tutorial and Blog are added by default, but you can add a list of other items, like the image above.

GitHub Icon Customization

Another item customized in this demo is the GitHub link. By default, it’s just plain text that links to GitHub. In this demo, the plain text was changed to an Icon.

In that part labeled “GitHub Icon,” replace the “label” with this:

 className: "header-github-link",
"aria-label": "GitHub repository",

Finally, navigate to src > CSS >custom.css and add the following CSS code.

.header--github-link {
  width: 32px;
  height: 32px;
  padding: 6px;
  margin-right: 4px;
  border-radius: 50%;
  transition: background var(--ifm-transition-fast);
}

.header--github-link:hover {
  background: var(--ifm-color-emphasis-200);
}

.header--github-link:before {
  content: '';
  height: 100%;
  display: block;
  background: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E") no-repeat;
}

html[data-theme='dark'] .header--github-link:before {
  background: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath fill='white' d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E") no-repeat;
}

The CSS code styles a GitHub link icon within a header, making it adaptable to light and dark themes.

Adding new pages to your Navbar

As stated earlier, the Tutorial and Blog are the default pages added at the navbar. There are two ways to add new pages, either as a single page or multiple documentation pages.

To create a single page, add this line of code to your docusaurus.config.js file inside the item array. We are creating a new Reference page.

{ to: "references", label: "Reference", position: "left" },

to: this specifies the path to which the navigation link will point.
label: this is the text displayed on the navigation bar.
position: this determines where the link will appear on the navigation bar. Position can either be set to left or right

For this page to work, you have to create the file in the src > pages folder and then you can fill it with markdown content.

Creating Multiple Documentation Sections in Docusaurus

Structuring your documentation into clear sections significantly improves user experience. While Docusaurus includes a default Tutorial section, you may want to create an additional documentation section. Here’s how you can do it:

In the docs folder, create a new folder called API. This folder will represent the API documentation section for this demo.
Add your Markdown files to the API folder. Each file will represent a different page within that section.
Navigate to sidebars.js file to include your new sections.

apiSidebar: [
    {
      type: 'category',
      label: 'API',
      items: ['api/overview','api/use-cases', 'api/faq'],
    },
  ],

apiSidebar: is the name of the sidebar, which can be referenced in the config file to specify where it should be used.
type: specifies that this item is a category, meaning it can contain multiple documents or other categories.
label:is the text that will be displayed in the sidebar for this category.
items: is a list of document IDs in the “API” category.

Finally, Configure the docusaurus.config.js file to add the new sections to the navbar.

          {
            type: "doc",
            sidebarId: "api",
            docId: "API/overview",
            position: "left",
            label: "API Documentation",
          },

After customization, the navbar looks like this in light and dark mode.

Color Palette Customization

Except your brand’s color is the same as Docusaurus’, you definitely want to change it. Docusaurus Classic preset uses the Infirma framework for styling, and you can override the style in your custom.css File.

Docusaurus provides a very useful tool for generating a color palette for your site. Enter the primary color for both your light and dark mode and it will help generate suitable color variables for both modes. Find it here. After generating these variables, replace them with the ones in your src/css/custom.css file.

Homepage Customization

Customizing your homepage is very important, especially if you have a design you’re trying to replicate. It’s not too complicated to customize; you can alter or rebuild the default Docusaurus page from scratch.

You can choose to customize your site either from src/pages/index.js or .docusaurus.config.js However, customizing from the Javascript file gives you easier access to better customization, as you can add other elements and styling. Note that you need a basic understanding of ReactJS to do this.

Customizing the Config file

First, navigate to your .docusaurus.config.js, and replace the title and tagline with the name of your site and then the default favicon with your own image.

P.S. A favicon is a small image displayed next to the page title in the browser tab.

Customizing the Javascript file

Navigate to your src/pages/index.js file and then begin your customization.
You will see a function similar to this.

Replace the {siteConfig} objects with your desired content. For example, in this demo, you will add new elements such as the span as the hero section pretext, a subheader section and a banner image.
Open your src/css/custom.css file and add your custom CSS styles. Ensure you import the custom CSS file into your src/pages/index.js, that’s the only way it till work.

function HomepageHeader() {
  return (
    <header className={clsx("hero hero--primary", styles.heroBanner)}>
      <div className="container">

          // hero section pretext

        <div className="hero__pretext">
          <span>Hands-on tutorial 🔥</span>
        </div>
        <Heading as="h1" className="hero__title">
          Get Started With Docs Site
        </Heading>

          // hero section subheader
        <p className="hero__subtitle">
          Docs Site is a comprehensive platform designed to help you create,
          manage, organize and share documentation effortlessly. Whether you're
          a developer, writer, or project manager.
        </p>
        <div className={styles.buttons}>
          <Link
            className="button button--secondary button--lg"
            to="/docs/intro"
            style={{ alignSelf: "left" }}
          >
            Let's Explore - 5min ⏱️
          </Link>
        </div>
      </div>

          // banner image
      <div className="banner__img">
        <img src={heroImage} alt="at something" />
      </div>
    </header>
  );
}

The other part of the homepage is the feature, and you can find the source code in src > components > index.js. You can make your desired changes to meet the design you’re working with. You can add more components by creating more Javascript files in the component folder.

Here’s what the docs-site demo looks like in light and dark mode.

If customizing the homepage feels too technical for you, consider seeking assistance from an engineer on your team, or for personal projects, you can remove the homepage entirely, making the default landing page the docs itself.
However, this tutorial will help you start the customization process.

Conclusion

Docusaurus is a powerful tool for creating documentation sites. Its intuitive setup and robust features offer a simple setup, a rich feature set, and a smooth development experience.

Setting up Docusaurus for the first time may seem very challenging, but this tutorial covers everything you need to know to set up Docusaurus.

Check out the demo built in this tutorial and the source code on GitHub.

If you found this guide helpful, be sure to check out the second part of this series: Implementing the Algolia Search Feature in Docusaurus. This article will walk you through the steps to add powerful search functionality to your documentation site. See here.