How to Install Docusaurus on linux

  CMS & Web development, Linux system administration
setup and Configure Docusaurus Static Site Generator

Docusaurus is a modern static website generator optimized for creating documentation websites. It provides a great out-of-the-box documentation experience with features like search, versioning, i18n, and more. In this comprehensive tutorial, we will go through step-by-step how to install Docusaurus on your system.

Prerequisites

Before installing Docusaurus, you need to have the following prerequisite software installed:

  • Node.js (>=12.13.0,<13.0.0 || >=14.15.0)
  • Yarn or NPM

Node.js

Docusaurus is built on React and requires Node.js to run.

$ node -v

This will print the installed version of Node. If it is less than 12.13.0 or between 13.0.0 and 14.15.0, you need to upgrade Node.js on your system.

To install Node.js, go to the official Node.js website and download the installer for your operating system. Follow the prompts to install Node.js.

Yarn or NPM

Docusaurus uses a package manager like Yarn or NPM to manage its dependencies. You need to have either Yarn or NPM installed.

To check if you have Yarn installed:

$ yarn --version

If Yarn is not installed, you can install it via npm:

$ npm install --global yarn

To check if you have NPM installed:

$ npm --version

NPM usually comes bundled with Node.js installation. If you don’t have it, you can install NPM from the official website.

Once you have verified the prerequisites, we can move on to installing Docusaurus.

Installing Docusaurus

There are two main ways to install Docusaurus – using the classic template or using a single command. We will cover both methods in this section.

1. Using the Classic Template

The classic template provides a project skeleton to get you started quickly with some example content. This is the recommended approach if you are new to Docusaurus.

To install Docusaurus using the classic template:

  1. Create a new directory for your Docusaurus site:
$ mkdir my-website
$ cd my-website
  1. Run the Docusaurus installation script with npx:
$ npx @docusaurus/init@latest init --template classic

This will install all the dependencies and create an initial project structure with some example docs, a blog, and custom pages.

  1. Start the Docusaurus development server:
$ cd my-website
$ npm start

The website will open up at http://localhost:3000/ where you can start adding content.

That’s it! Docusaurus is now installed and running using the classic template.

2. Using a Single Command

You can also scaffold a bare Docusaurus site using a single npx command:

$ npx @docusaurus/init@latest init

This will install Docusaurus and create a minimal project structure without any docs or example content.

To start the development server:

$ cd my-website
$ npm start

This approach gives you a blank slate to build your docs site however you want. But you will have to add the docs, blog, custom pages, etc yourself.

Project Structure

Once Docusaurus is installed, you will see a generated folder structure like this:

my-website
├── blog
├── docs
├── src
│   ├── css
│   └── pages 
├── static
├── package.json
├── sidebars.js
├── docusaurus.config.js
└── .gitignore

Here is what each of these folders and files are for:

  • /blog – Contains the blog posts that will appear in the blog section.
  • /docs – Contains the Markdown files for the docs that will appear in the docs section.
  • /src – Contains the React components, CSS files, static pages and other source code.
  • /src/css – CSS files for styling the site.
  • /src/pages – Static pages like the home page, about page, contact page etc.
  • /static – Static assets like images, pdfs etc go here.
  • package.json – The NPM dependencies and scripts for development.
  • sidebars.js – Configuration for the left sidebar navigation.
  • docusaurus.config.js – Main site configuration file.
  • .gitignore – Tells git which files not to track.

Running the Development Server

To preview your site locally, you can run the Docusaurus development server:

$ npm start

This will start the development server at http://localhost:3000/ and rebuild the website as you make changes.

The hot reloading feature will automatically refresh the page as you edit the files.

Configuring Docusaurus

The main configuration file is docusaurus.config.js located at the root.

This file contains settings for:

  • Site metadata like title, tagline, url, favicon etc.
  • Header and footer navigation links.
  • Color theme.
  • Custom CSS and JavaScript
  • Custom Markdown plugins
  • Adding custom pages
  • Registration of Docs, Blog, Custom pages
  • And many more configuration options.

For example, to change the site title:

// docusaurus.config.js
module.exports = {
  title: 'My Site Title',
  tagline: 'The tagline of my site',
  // ...
}

Refer to the Docusaurus configuration docs for the full list of options.

The sidebars.js file is used to configure the left side navigation for the docs. It allows you to specify which documents should be included in the sidebar and in what order.

For example:

// sidebars.js
module.exports = {
  tutorialSidebar: [
    'intro',
    'install',
    {
      type: 'category',
      label: 'Guides',
      items: [
        'guide1',
        'guide2'
      ]
    }
  ],
}

This maps the document intro.md to the sidebar item “Introduction”, install.md to “Installation” and so on.

The Docusaurus documentation provides a complete reference for all configuration options.

Creating Pages

To add a new page like “About Us”, create a JSX file at src/pages/about.js:

// src/pages/about.js
import React from 'react';
function About() {
  return (
    <main>
      <h1>About Us</h1>
      <p>This page tells you all about us...</p>
    </main>
  )
}
export default About;

This React component will be rendered as a page at the route /about.

Similarly, you can add pages like /contact, /pricing, /terms etc.

Refer to the Docusaurus docs on pages for more details.

Adding Blog Posts

To create a new blog post, add a Markdown file to the blog directory. For example:

blog/welcome.md:

---
slug: welcome
title: Welcome to my Blog
author: John Doe
author_title: Principal Author
author_url: https://github.com/john
author_image_url: https://avatars3.githubusercontent.com/u/123?s=400&v=4  
tags: [hello, docusaurus]
---
Welcome to my new blog! This is my first post.
I will write about my journey with Docusaurus and share my thoughts. Stick around for more to come!

The post attributes allow you to customize the blog header. Docusaurus will read these Markdown files and generate a nice blog page for each post.

Refer to the Docusaurus blog docs for more details on creating blog posts.

Adding Documentation

To add documentation pages, create Markdown files inside the /docs folder.

For example:

docs/intro.md

# Introduction
Welcome to my documentation site!
I will cover how to install Docusaurus and discuss key concepts.

docs/install.md

# Installation
You can install Docusaurus using:
```bash
npm init docusaurus@latest
```
This will get you up and running quickly.

The Markdown files will be converted to HTML and rendered nicely with features like a sidebar, navigation, search etc.

You can use headings, images, links, code blocks, syntax highlighting and Markdown formatting.

Refer to the Docusaurus documentation docs for more details on the Markdown features available.

Versioning

Docusaurus makes it easy to maintain documentation versions with the versions feature.

To use versioning, first initialize the docs:

$ npm run docusaurus docs:version 1.0.0

This will create a versioned_docs folder and copy your existing docs folder contents into versions/1.0.0 subfolder.

You can then make changes to the docs in the docs folder which will be reflected in the latest version.

To create a new version:

$ npm run docusaurus docs:version 1.0.1

This will copy the current docs folder into versions/1.0.1 as a snapshot. You can switch between versions by selecting them in the version dropdown.

Refer to the Docusaurus versioning guide for more details.

Themes

Docusaurus comes with several themes including:

  • Classic – The classic Docusaurus theme.
  • Bootstrap – A theme with Bootstrap styles.
  • Minimal – A minimal theme with plain CSS.

The theme can be configured in docusaurus.config.js:

module.exports = {
  // ...
  themeConfig: {
    navbar: {
      title: 'Site Title',
      logo: {
        alt: 'Site Logo',
        src: 'img/logo.svg',
      } 
    },
  },
  themes: ['@docusaurus/theme-classic'],
}

You can also create custom themes to brand your site.

Refer to the theming docs for details on theming components like navbars, footer, color palette etc.

Deployment

Once your Docusaurus site is ready, you can deploy it easily.

First, build the static HTML pages:

$ npm run build

This will generate a build folder containing the HTML pages, JavaScript bundles and assets.

You can now deploy the build folder to any static hosting provider like GitHub Pages, Vercel, Netlify, Azure Static Web Apps etc.

For example, to deploy on GitHub pages:

  1. Commit the build folder to a gh-pages branch on GitHub.
  2. Set the GitHub pages site to point to the gh-pages branch.

Refer to the Docusaurus deployment docs for guides on deploying to various platforms.

And that’s it! Your Docusaurus site should now be published online.

Summary

In this tutorial, we went through how to:

  • Install Docusaurus using the classic template or single command
  • Structure the project files and folders
  • Configure Docusaurus using docusaurus.config.js
  • Run the development server
  • Create React pages
  • Add blog posts
  • Organize documentation with Markdown
  • Version documentation
  • Theme Docusaurus site
  • Deploy Docusaurus on production

Docusaurus is a great tool for building documentation websites with React. It provides a nice out-of-the-box experience while giving flexibility to customize and extend anything. I hope you found this tutorial helpful in learning how to get started using Docusaurus for your docs site.

LEAVE A COMMENT