How to use the multi-blog plugin for Docusaurus

Contents

• Why I wrote this
• What's Docusaurus?
• Requirements
• Instructions
  • Step 1. Create a Docusaurus project.
  • Step 2. Open the project in a code editor
  • Step 3. Add the second blog's folder and file
  • Step 4. Add the multi-blog plugin to docusaurus.config.js
  • Step 5. Run the dev server and view your site
  • Next steps

Why I wrote this

Recently, I helped someone who had trouble installing the multi-blog plugin for Docusaurus. The instructions on their website are not clear for non-technical users, and she kept getting a 404 Not Found when trying to access the second blog. This post expands on their instructions with more details and screenshots for less technical users.

What's Docusaurus?

Docusaurus is a Jamstack SSG (Static Site Generator) mainly intended for documentation and blog websites. It is a Meta Open Source project. It is configured with a JavaScript file called docusaurus.config.js.

Requirements

• Node.js 18 or above installed
  • Instructions for installing Node.js using a version manager
• Some familiarity with a CLI (Command Line Interface)
• An IDE or code editor
  • I recommend Visual Studio Code

Instructions

Step 1: Create a Docusaurus project

If you don't already have a Docusaurus project, create one now using the npx CLI command:

npx create-docusaurus@latest twoblogs classic

npx is a CLI tool bundled with Node.js that lets you access code packages hosted by the organization called NPM (Node Package Manager). In this case, npx accesses and runs the create-docusaurus package with the classic template. If the command succeeds, it creates a folder on your computer named twoblogs/.

Step 2: Open the project in a code editor

Open the newly created project folder in your code editor. If you use VS Code, the following command (run from the same location where you ran the previous command) will open the twoblogs/ folder in VS Code:

code twoblogs

In VS Code, the newly created project's structure looks like this:

Step 3: Add the second blog's folder and file

In the twoblogs/ folder, create a new folder named blog2/. In it, create a new file named index.md. Write the text # Hello World in index.md:

Step 4: Add the multi-blog plugin to docusaurus.config.js

Open the file docusaurus.config.js. The next step is to add a plugins object as a property of the config object defined in this file.

Scroll down until you see the themeConfig object:

Above it, add the following code:

  plugins: [
    [
      '@docusaurus/plugin-content-blog',
      {
        id: 'blog2',
        routeBasePath: 'blog2',
        path: './blog2',
      },
    ],
  ],

The file should now look like this:

Step 5: Run the dev server and view your site

Open a CLI shell to the twoblogs/ folder. In VS Code, you can do this by going to the Terminal menu across the top and choosing New Terminal. (Or use a keyboard shortcut: Ctrl+j for Windows, or Cmd+j for macOS.)

Enter the following command in your CLI shell:

npm run start

Expected output:

Ignore the yellow warning about git. For a production site, you would want to add a git repository as the warning indicates, but it is not necessary for this quick tutorial. Your only concern for now is to make sure you see the final line that says "compiled successfully".

Your default browser should open automatically to http://localhost:3000/. Add blog2 to the end of the URL and you should see your second blog's index.md page displayed:

That's it! If you can see your Hello World message, your multi-blog plugin is working.

What's next?

• Learn how to deploy your site
• Learn more about Docusaurus
• Learn more about Docusaurus blogs
• Join the Docusaurus community on Discord