How to Install Docusaurus on Linux

By Posted on

How to Install Docusaurus on Linux

How to Install Docusaurus on Linux

[Include Image Here: Docusaurus 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. Setting up Docusaurus on Linux can be a straightforward process, enhancing your documentation workflow.

Prerequisites

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

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 project directory and navigate into it:
$ mkdir my-website
$ cd my-website
  1. Initialize a new Docusaurus project using the classic template:
$ 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. Navigate into the project directory and start the 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 your blog posts (Markdown or MDX files).
  • docs: Contains your documentation pages (Markdown or MDX files).
  • src: Contains custom React components, CSS, and pages.
  • src/css: Holds custom CSS stylesheets.
  • src/pages: Contains custom React pages.
  • static: Contains static assets like images, fonts, etc.
  • package.json: Contains project metadata and dependencies.
  • sidebars.js: Configures the sidebar navigation for the documentation.
  • docusaurus.config.js: Contains the main Docusaurus configuration.
  • .gitignore: Specifies intentionally untracked files that Git should ignore.

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 (title, tagline, URL, etc.)
  • Theme configuration (navbar, footer, etc.)
  • Plugins and presets
  • Custom CSS and JavaScript

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](https://docusaurus.io/docs/markdown-features) 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:

```bash
$ 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 Theme
  • Dark Mode
  • Custom Themes

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. Configure GitHub Actions to deploy your site.
  2. Commit and push your changes to GitHub.
  3. Your site will be automatically deployed.

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 on Linux
  • Create a new Docusaurus project
  • Configure Docusaurus
  • Add documentation pages
  • Add blog posts
  • Deploy Docusaurus

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.

Alternative Installation Methods

While the methods described above are the most common, here are a couple of alternative approaches to installing Docusaurus, especially relevant in specific Linux environments:

1. Using Docker

Docker provides a containerized environment, which can be useful for consistent deployments and isolating Docusaurus from your host system’s dependencies. This is especially valuable if you have complex system dependencies or need to ensure identical environments across different machines.

Explanation:

Instead of directly installing Node.js and Yarn/NPM on your Linux system, you can use a Docker image that already contains these dependencies. You then mount your Docusaurus project directory into the container, allowing the container to build and serve your site.

Code Example (Docker):

First, create a Dockerfile in your Docusaurus project’s root directory:

# Use a Node.js base image
FROM node:16-alpine

# Set the working directory inside the container
WORKDIR /app

# Copy package.json and package-lock.json (or yarn.lock)
COPY package*.json ./
# Or if you use yarn:
# COPY yarn.lock ./

# Install dependencies
RUN npm install
# Or if you use yarn:
# RUN yarn install

# Copy the rest of the application code
COPY . .

# Expose the port Docusaurus will run on
EXPOSE 3000

# Command to start the Docusaurus development server
CMD ["npm", "start"]
# Or if you use yarn:
# CMD ["yarn", "start"]

Then, build the Docker image:

docker build -t docusaurus-app .

Finally, run the Docker container, mapping port 3000 on your host to port 3000 in the container, and mounting your project directory:

docker run -p 3000:3000 -v $(pwd):/app docusaurus-app

Now you can access your Docusaurus site at http://localhost:3000. The -v $(pwd):/app option mounts your current directory into the /app directory inside the container, allowing you to make changes to your code and see them reflected in the running application.

2. Using a Package Manager Specific to Your Linux Distribution

Many Linux distributions have their own package managers (e.g., apt on Debian/Ubuntu, yum on Fedora/CentOS, pacman on Arch Linux). While these package managers don’t directly install Docusaurus, they can be used to install Node.js and Yarn/NPM, simplifying the prerequisite installation.

Explanation:

Using your distribution’s package manager can be more convenient than downloading and installing Node.js directly from the Node.js website. It also ensures that the installed Node.js version is compatible with your system.

Code Example (apt – Debian/Ubuntu):

First, update your package lists:

sudo apt update

Then, install Node.js:

sudo apt install nodejs npm

This command installs both Node.js and NPM. Note that the version of Node.js available through apt might not always be the latest. To install a more recent version, you might need to add a NodeSource repository:

curl -sL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt-get install -y nodejs

Finally, install Yarn globally:

sudo npm install -g yarn

After installing the prerequisites using apt, you can proceed with the standard Docusaurus installation methods described earlier in the article. This approach centralizes package management, which can be beneficial for system administration.

Related posts: