Skip to main content

Build A Documentation Site With Docusaurus From Zero

If your goal is to build a knowledge base, documentation site, or blog-style content site, Docusaurus is a strong starting point.

Its value is not just "you can write Markdown." It packages these foundational pieces for you:

  • Document routing
  • Sidebar
  • Search integration
  • Static builds
  • Blog system
  • Theme and extension capabilities

Why It Is Good For a First Site​

The biggest fear when building a first site is dealing with too many dimensions at once:

  • Frontend page structure
  • Routing
  • Building
  • Deployment
  • SEO basics
  • Site organization

Docusaurus scaffolds all of this first, so you can focus more on content and information architecture.

Minimum Steps To Set Up a Docusaurus Site​

1. Prepare the Node.js Environment​

This repository currently requires node >= 18.

2. Initialize the Project​

npx create-docusaurus@latest my-website classic

3. Enter the Directory and Start Locally​

cd my-website
npm install
npm start

4. Understand the Key Directories​

my-website
├── docs
├── blog
├── src
├── static
├── docusaurus.config.js
└── sidebars.js

Where:

  • docs holds document content
  • blog holds blog posts
  • src holds pages, components, and styles
  • static holds assets that are copied as-is to the build output

What Projects Is Docusaurus Best Suited For​

Well Suited​

  • Documentation sites
  • Personal knowledge bases
  • Technical blogs
  • Project description sites

Not Ideal For​

  • Complex admin systems
  • Highly interactive web apps
  • Products that heavily depend on real-time user data

When Writing Content, Structure Matters More Than Markdown​

What truly determines the quality of a documentation site is usually not the syntax, but:

  • Whether the directory hierarchy is clear
  • Whether entry pages exist
  • Whether main paths and quick references are separated
  • Whether old content can be archived instead of piling up

This is also the core idea behind the WebNotes restructuring.

Local Development and Production Are Different Things​

Local Development​

npm start is for editing and previewing.

Production Deployment​

Production depends on the build output:

npm run build

After building, you get static files. From there you can:

  • Host on a static platform
  • Put them in object storage + CDN
  • Serve them through Nginx

Common Mistakes When Using Docusaurus for the First Time​

1. Writing Articles Without Designing Entry Pages​

The result is more and more content, but nobody knows where to start reading.

2. Letting the Directory Structure Grow Organically by File Name​

You will quickly lose your information architecture.

3. Treating "It Runs Locally" as "Ready To Deploy"​

Local preview does not mean the production access chain is configured.

4. Not Thinking Through Static Asset Paths and Deployment Paths​

Once you connect a CDN, object storage, or sub-path deployment, resource references can easily break.

How This Repository Implements i18n​

This site uses Docusaurus i18n for a bilingual Chinese-English setup. The default locale is zh-Hans, and the English locale is en. This means Chinese pages stay at the root path, such as /docs/intro, while English pages are under the /en/ prefix, such as /en/docs/intro.

The relevant configuration is in docusaurus.config.js:

  • i18n.defaultLocale stays as zh-Hans
  • i18n.locales includes both zh-Hans and en
  • A localeDropdown is added to the navbar

Common commands for local maintenance:

npm start
npm run start:en
npm run build
npm run build:en
npm run write-translations:en

npm run build builds all languages and must be run before committing. npm run build:en is useful for quickly verifying changes to English translations or the English UI only.

Translation files live in i18n/en/:

  • Blog post translations: i18n/en/docusaurus-plugin-content-blog/
  • Docs translations: i18n/en/docusaurus-plugin-content-docs/current/
  • Sidebar, category labels, navbar, footer translations: corresponding plugin or theme JSON/YAML files

The easiest thing to miss is custom React pages. Docusaurus handles Markdown and configuration-based text, but does not automatically translate strings inside custom components. Pages like the docs homepage, Travel homepage, Blog overview page, and site homepage — which have been heavily customized — all need to read the current locale inside the component:

const {
  i18n: {currentLocale},
} = useDocusaurusContext();

Then select the corresponding copy, card titles, stat labels, and empty states based on currentLocale. This way the English pages keep the original design layout instead of falling back to a plain documentation page.

The Travel section has one more consideration: the page layout depends on src/utils/travelDocs.js to determine whether the current path belongs to Travel. When maintaining this, you must support both /docs/Travel... and /en/docs/Travel.... If you only match the Chinese root path, the English Travel page will load but will lose the Travel-specific wide layout and hidden sidebar rules.

Practical Advice For Building a First Documentation Site​

  1. Get the content structure right before pursuing theme styling
  2. Get building and deployment working before gradually adding components
  3. Understand what docs, blog, src, and static each handle
  4. Always run an actual build before going live