Introduction to Docusaurus

Dinosaurs taking over Documentation

Docusaurus is a static site generator created by Facebook, specifically tailored for building project documentation websites.

Docusaurus is built on React, allowing developers to use modern web technologies. It features Markdown-based documentation. One of its main advantages is MDX, a format that allows you to import React components into a Markdown file. This makes it an excellent choice for projects that need rich, interactive documentation websites.

Setting Up Docusaurus

To start with Docusaurus, you’ll need Node.js installed on your system. Here’s a brief setup guide for a new Docusaurus project.

Open your terminal and run the following command to create a new project:

npx create-docusaurus@latest my-docs classic

This process creates a new site using the “classic” template, which includes typical documentation settings and a blog. I recommend to choosing TypeScript during the installation process.

Navigate into your project directory and start the development server:

cd my-docs
npm start

That starts the local development server under http://localhost:3000/.

Dockerizing Docusaurus

I recommend Dockerize the setup to avoid cluttering your system. Create a Dockerfile that instructs how to build a Docker image for your site. Here’s an example:

FROM node:20.13.0 as builder

ENV NODE_PATH=/app/node_modules

WORKDIR /app

COPY .npmrc package*.json /app/
RUN npm install

COPY . /app
RUN npm run build

FROM nginx:latest

COPY --from=builder /app/build /usr/share/nginx/html
EXPOSE 80

This example will serve the production build through nginx.

To run it locally, create a docker-compose.yml file with the following content:

version: '3'

services:
  web:
    build:
      context: .
      target: builder
    ports:
      - '8000:80'
    volumes:
      - '.:/app:rw'
      - 'node_modules:/app/node_modules'
    command: npm start -- --port 80 --host 0.0.0.0

volumes:
  node_modules:

Finally, start the application by running:

docker compose build
docker compose up

You can also create a template from it and deploy it to Divio Cloud with ease, getting a full fledged hosted solution with certificates and all.

Alternatives to Docusaurus

• MkDocs: A fast, simple, downright gorgeous static site generator geared towards building project documentation. Documentation source files are written in Markdown and configured with a single YAML configuration file.
• Sphinx: This tool is used primarily for Python documentation and supports reStructuredText as its markup language. It boasts a wealth of extensions and themes, which makes it a versatile tool for more complex documentation needs.
• Jekyll: Often used for personal, project, or organization sites. Jekyll allows using HTML, CSS, and JavaScript alongside Markdown, Liquid templating, and more to create customized websites. It’s also supported natively by GitHub Pages, making it easy to deploy.
• VuePress: Similar to Docusaurus, VuePress is optimized for technical documentation. It leverages Vue.js for theming and enhancing content. VuePress features a minimal setup with a markdown-centered project structure, and everything is generated as a static site.

Summary

Docusaurus is a robust solution for anyone looking to build a documentation website quickly and efficiently, especially if they are already familiar with React. Dockerizing your Docusaurus project can further streamline the deployment process, making it more consistent across different environments. Exploring alternatives like MkDocs, Sphinx, Jekyll, or VuePress could also be beneficial, depending on your specific needs.

‘Till next time!