Build a Manual with Docusaurus #1: From Install to Your First Doc

Framework Docusaurus Documentation Static Site
3 min read

When you start building documentation in earnest, you almost always run into the same problem: where do you put the documentation that a single README can no longer handle? Notion makes public sharing and version control awkward, and a blog tool just lists posts in chronological order, which is inconvenient as a reference. So many teams have moved toward treating docs like code — Docs as Code: write in Markdown, manage with Git, and deploy as a static site.

This series covers the first step of that approach, building a documentation site with a static site generator. The tool is Docusaurus. It’s built with React, and its strengths are MDX, which lets you use React components inside Markdown, and first-class support for multilingual and versioning. Installation is heavier than Hugo or MkDocs, but the ceiling is correspondingly higher.

This series, Build a Manual with Docusaurus, runs in six parts.

  • #1 From Install to Your First Doc ← this post
  • #2 Sidebar and Search — Structuring Your Documentation
  • #3 Writing Content — Code Blocks, Mermaid, Admonitions
  • #4 Deploy to Cloudflare Pages and Connect a Domain
  • #5 Multilingual and Versioning
  • #6 Maintenance — Search, Accessibility, and Documentation Culture

In this post we’ll cover what Docusaurus requires as prerequisites, and creating a new site and serving your first doc on the dev server, working through each step hands-on.

Prerequisite — Node.js #

Docusaurus is a tool that runs on Node.js. So the prerequisite is Node.js version 18 or higher. After installing, check the version.

Check the version 
node --version

Installing Node also installs the package manager npm. Unlike Hugo, which was a single binary, and MkDocs, which was a Python package, Docusaurus runs on top of the JavaScript ecosystem.

Creating a New Site #

The generator scaffolds the site for you in one go. Using the classic template gives you a starting point that includes docs, a blog, and the default theme.

Create a new site 
npx create-docusaurus@latest my-docs classic

When the command finishes, the my-docs folder contains all the necessary files, with dependencies already installed.

Serving Your First Doc #

Move into the created folder and start the dev server.

Run the dev server 
cd my-docs
npm start

The browser opens http://localhost:3000 automatically, showing the default docs. Edit a file and the page updates instantly. The doc body lives in the docs folder, and the first page is docs/intro.md. Let’s open this file and change its contents.

docs/intro.md 
---
sidebar_position: 1
---

# Getting started

This is our team's official documentation. Pick an item from the sidebar on the left.

sidebar_position sets the order in the sidebar. The smaller the number, the higher it appears.

Understanding the Folder Structure #

A few places in the generated structure are worth knowing right away.

Folder structure 
my-docs/
├─ docusaurus.config.js   # Site configuration
├─ sidebars.js            # Sidebar definition
├─ docs/                  # Doc body (fill this in)
│  └─ intro.md
├─ src/                   # Custom pages and React components
├─ static/                # Static files such as images
└─ build/                 # npm run build output (for deployment)

Growing your documentation means adding Markdown files under docs. Unlike Hugo, which uses the folder structure directly as the sidebar, Docusaurus defines the sidebar in sidebars.js. We’ll cover that in earnest in the next post.

Wrapping Up #

In this post we set up Node.js, created a site with create-docusaurus, and served our first doc on the dev server. The installation is heavy, but for teams already comfortable with React and JavaScript, it’s the tool that feels most natural in hand.

In the next post we’ll cover the sidebar and search. Even as docs grow into dozens of pages, we’ll design the information structure with sidebars.js so readers never lose their way.

X