Building Professional Documentation Sites with Docusaurus

Building Professional Documentation Sites with Docusaurus

ยท

9 min read

A Step-by-Step Guide to Create, Customize, and Deploy

Introduction ๐Ÿ’ก

As a developer or technical writer, creating a well-organized and easy-to-navigate documentation site is essential to help users quickly find information and understand how to use your product or service. Markdown is a lightweight markup language that is widely used for writing technical documentation because it is easy to write and read, and can be converted into various formats. Docusaurus is a popular open-source static site generator that can help you create beautiful and responsive documentation sites with ease.

In this step-by-step guide, we'll walk you through how to build a Markdown documentation site with Docusaurus.

Step 1: Install Docusaurus

Before we start building our documentation site, we need to install Docusaurus. Docusaurus is a Node.js-based tool, so we need to make sure that Node.js and npm (Node Package Manager) are installed on our computer. To install Docusaurus, we'll use npm.

Open a terminal or command prompt and run the following command:

npm install --global docusaurus-init

This command installs the Docusaurus command-line interface (CLI) globally on our computer. Once the installation is complete, we can use the docusaurus-init command to create a new Docusaurus project.

Step 2: Create a new Docusaurus project

To create a new Docusaurus project, run the following command:

docusaurus-init my-docs

Replace my-docs with the name of your project. This command creates a new directory with the specified name and sets up a basic Docusaurus project structure inside it. The project structure includes the following files and directories:

  • docs/: This directory is where we'll put our Markdown documentation files.

  • website/: This directory contains the Docusaurus configuration files, such as docusaurus.config.js and package.json.

  • node_modules/: This directory contains the dependencies that our project requires.

  • static/: This directory is where we'll put any static assets, such as images or CSS files.

Step 3: Customize the Docusaurus configuration

Now that we have our project structure set up, we can customize the Docusaurus configuration to suit our needs. The configuration files are located in the website/ directory.

Configuring the site title and tagline

Open the docusaurus.config.js file in a text editor and change the title and tagline fields to the title and tagline of your documentation site. For example:

module.exports = {
  title: 'My Documentation Site',
  tagline: 'This is the tagline for my documentation site',
  // ...
};

Configuring the site URL and base URL

By default, Docusaurus assumes that the documentation site will be hosted at the root of a domain (e.g. https://example.com). If you're hosting your documentation site on a subpath (e.g. https://example.com/docs/), you need to configure the site URL and base URL.

Open the docusaurus.config.js file and add the following fields to the url and baseUrl objects:

module.exports = {
  url: 'https://example.com',
  baseUrl: '/docs/',
  // ...
};

Replace https://example.com with the URL of your documentation site, and /docs/ with the base URL of your documentation site.

Configuring the navigation bar

The navigation bar is the bar at the top of the documentation site that contains links to the different pages of the site. To configure the navigation bar, open the docusaurus.config.js file and add the following fields to the nav array:

module.exports = {
  // ...
  themeConfig: {
    navbar: {
      title: 'My Documentation Site',
      logo: {
        alt: 'My Site Logo',
        src: 'img/logo.svg',
      },
      items: [
        {
          to: 'docs/introduction',
          activeBasePath: 'docs',
          label: 'Docs',
          position: 'left',
        },
        { to: 'blog', label: 'Blog', position: 'left' },
        {
          href: 'https://github.com/myusername/myproject',
          label: 'GitHub',
          position: 'right',
        },
      ],
    },
    footer: {
      // ...
    },
  },
  // ...
};

This example adds three items to the navigation bar:

  • A link to the docs/introduction.md file, with the label "Docs".

  • A link to the blog/ directory, with the label "Blog".

  • A link to a GitHub repository, with the label "GitHub".

The to field specifies the URL or path of the page or directory that the link points to. The activeBasePath field specifies the base path for the link to be considered active. The label field specifies the text to display in the link. The position field specifies the position of the link in the navigation bar, either "left" or "right".

Configuring the sidebar

The sidebar is the menu on the left-hand side of the documentation site that contains links to the different sections and pages of the site. To configure the sidebar, we need to create a sidebars.js file in the website/ directory. The sidebars.js file is where we define the structure and content of the sidebar.

Create a new file named sidebars.js in the website/ directory and add the following code:

module.exports = {
  docs: {
    Introduction: ['introduction'],
    Features: ['feature-1', 'feature-2'],
    // ...
  },
};

This example defines a docs section with three pages: "Introduction", "Feature 1", and "Feature 2". The page titles correspond to the Markdown file names (e.g. introduction.md).

Adding content to the documentation site

Now that we have the Docusaurus configuration set up, we can start adding content to our documentation site. Create a new file named introduction.md in the docs/ directory and add the following Markdown content:

---
id: introduction
title: Introduction
---

# Welcome to my documentation site

This is the introduction page for my documentation site.

This Markdown content defines the title and ID of the page, and the content of the page itself.

To add more pages to the documentation site, create new Markdown files in the docs/ directory and update the sidebars.js file to include the new pages.

Step 4: Customize the styling of the documentation site

Docusaurus comes with a default theme that provides a clean and professional look for the documentation site. However, we can customize the styling of the site to match our branding or personal preferences.

Changing the color scheme

To change the color scheme of the site, open the docusaurus.config.js file and add the following field to the themeConfig object:

module.exports = {
  // ...
  themeConfig: {
    // ...
    colorMode: {
      defaultMode: 'light',
      disableSwitch: false,
      respectPrefersColorScheme: false,
      switchConfig: {
        darkIcon: '<i class="fa fa-moon"></i>',
        lightIcon: '<i class="fa fa-sun"></i>',
      },
    },
  },
  // ...
};

This example sets the default color mode to "light" and enables the color mode switch in the navigation bar. The disableSwitch field specifies whether to disable the color mode switch. The respectPrefersColorScheme field specifies whether to use the system's color scheme as the default mode. The darkIcon and lightIcon fields specify the icons to use for the dark and light modes, respectively.

You can also customize the colors of the site by editing the src/css/custom.css file. For example, to change the background color of the site, add the following CSS rule:

body {
  background-color: #f9f9f9;
}

To customize the logo of the site, replace the website/static/img/logo.svg file with your own logo file. You can also edit the size and position of the logo by adding the following field to the themeConfig object:

module.exports = {
  // ...
  themeConfig: {
    navbar: {
      // ...
      logo: {
        alt: 'My Site Logo',
        src: 'img/logo.svg',
        // ...
        width: 100,
        height: 50,
      },
    },
    // ...
  },
  // ...
};

This example sets the width and height of the logo to 100 and 50 pixels, respectively. You can also use the className field to add custom CSS classes to the logo element.

Customizing the font

To customize the font of the site, add the following field to the themeConfig object:

module.exports = {
  // ...
  themeConfig: {
    // ...
    font: {
      family: 'Arial',
      size: 16,
      weight: 'normal',
    },
  },
  // ...
};

This example sets the font family to "Arial", the font size to 16 pixels, and the font weight to "normal". You can also use the googleFonts field to specify Google Fonts to load, and the codeFonts field to specify the font for code blocks.

Step 5: Deploy the documentation site

Once you have customized the documentation site to your liking, it's time to deploy it so that others can access it. There are several options for deploying a Docusaurus site, including hosting it on a web server, using a static site hosting service, or deploying it to a cloud service like AWS or Azure.

Hosting on a web server

To host the documentation site on a web server, copy the built files from the build/ directory to your web server's document root directory. You can use a tool like rsync to copy the files over:

rsync -av build/ myserver:/var/www/html/

Replace myserver with the hostname or IP address of your web server, and /var/www/html/ with the document root directory.

Static Site hosting service : Netlify, GitHub Pages, or Vercel.

These services provide a simple way to host your Docusaurus site and deploy changes quickly.

Deploying to GitHub Pages

To deploy your Docusaurus site to GitHub Pages, follow these steps:

  1. Push your changes to the main branch:

     git add .
     git commit -m "Update documentation"
     git push origin main
    
  2. Install the gh-pages package:

     yarn add -D gh-pages
    
  3. Update the docusaurus.config.js file to include the baseUrl and trailingSlash fields:

     module.exports = {
       // ...
       url: 'https://username.github.io',
       baseUrl: '/my-docs/',
       trailingSlash: true,
       // ...
     };
    

    Replace username with your GitHub username and my-docs with the name of your repository.

  4. Add a new script to the package.json file:

     "scripts": {
       // ...
       "deploy": "docusaurus deploy",
       // ...
     }
    
  5. Run the deploy script:

     yarn deploy
    
  6. Wait for the deployment to complete. Once it's finished, your documentation site will be available at https://username.github.io/my-docs/.

Deploying to Netlify

To deploy your Docusaurus site to Netlify, follow these steps:

  1. Sign up for a Netlify account if you don't already have one.

  2. Create a new site in Netlify and connect it to your GitHub repository.

  3. Configure the build settings in Netlify:

    • Build command: yarn build

    • Publish directory: build/

  4. Save the settings and trigger a new deploy.

  5. Wait for the deployment to complete. Once it's finished, your documentation site will be available at a Netlify URL like https://my-docs.netlify.app/.

Deploying to Vercel

To deploy your Docusaurus site to Vercel, follow these steps:

  1. Sign up for a Vercel account if you don't already have one.

  2. Connect your Docusaurus project to Vercel using the Vercel CLI:

     yarn global add vercel
     vercel login
     cd my-docs
     vercel init
    
  3. Follow the prompts to configure your deployment settings.

  4. Deploy the project:

     vercel deploy
    
  5. Wait for the deployment to complete. Once it's finished, your documentation site will be available at a Vercel URL like https://my-docs.vercel.app/.

Conclusion ๐Ÿš€

Congratulations, you've successfully built and deployed a documentation site with Docusaurus! With this powerful tool, you can create professional-looking documentation sites with ease, and keep your users up-to-date with your latest releases and updates.

ย