Setup Guide (Help)

This page documents the full process of building this site: environment check → init → docs-only config → TypeScript type-checking → build & serve → access verification. Use it as a reference for reproduction or troubleshooting.

TL;DR

Once your environment is ready, the steps below produce the same structure as this site (TypeScript + docs-only). Then open http://localhost:3000/ — the root path shows docs directly.

npx create-docusaurus@latest . classic --typescript   # 1. init (TS template)
npm run build                                         # 2. build check
npm run start                                         # 3. start dev server

1. Prerequisites

Docusaurus requires Node.js 18+ (this project tested with v24.7.0, npm 11.5.1). Verify before starting:

node -v          # expect v18+; this project uses v24.7.0
npm -v           # should be available
npm ping         # verify registry access; PONG = ok

# Check port 3000 is free (default dev server port)
ss -tlnp | grep ':3000' || echo '3000 free'

No Node.js?

Install and manage Node versions with nvm:

nvm install --lts
nvm use --lts

2. Initialize the project (TypeScript template)

If the target directory is empty, initialize it directly in the current directory (use . as the path):

npx create-docusaurus@latest . classic --typescript

The classic template ships docs + blog + preset pages — the best starting point.
--typescript generates .ts/.tsx configs and components, plus a tsconfig.json.
The scaffold auto-runs npm install, producing docusaurus.config.ts, sidebars.ts, docs/, blog/, src/, static/, etc.
The version obtained here is create-docusaurus@3.10.1.

⚠️ About the interactive prompt

The scaffold asks which language to use (JavaScript / TypeScript). With --typescript already set, this is skipped.

In a real terminal, use arrow keys to choose.

In a script / non-interactive environment (e.g. piped), feed the answer explicitly or it will hang:

printf '\n' | npx create-docusaurus@latest . classic --typescript   # pick default non-interactively

note

This site uses a TypeScript configuration.

3. Configure docs-only mode (root path shows docs directly)

This site removes the standalone home page: visiting / shows the first doc directly, with the URL staying /. This is Docusaurus docs-only mode — three changes:

Add routeBasePath: '/' to the docs preset in docusaurus.config.ts:

presets: [
  [
    'classic',
    {
      docs: {
        routeBasePath: '/',     // docs served at root path
        sidebarPath: './sidebars.ts',
      },
      blog: { /* ... */ },
    },
  ],
],

Delete src/pages/index.tsx (otherwise / collides with the docs home route).
Add slug: / to the doc that serves as the home page (here docs/getting-started.mdx):
```
---
sidebar_position: 0.5
slug: /
---
```

URLs change

Under docs-only mode, all doc URLs change from /docs/xxx to /xxx (e.g. /docs/intro → /intro). Any absolute /docs/... links in the navbar/footer must be updated, or onBrokenLinks: 'throw' will fail the build.

4. TypeScript type-checking

docusaurus build / start transpile TS via SWC and do not type-check; run it separately:

npm run typecheck

Two pitfalls (from practice)

TypeScript version conflict: create-docusaurus may install typescript@7.x in some environments, while @docusaurus/tsconfig still uses baseUrl — removed in TS 7, causing TS5102. Fix by downgrading to 5.x:
```
npm install --save-dev typescript@5
```
baseUrl must be declared explicitly in tsconfig: when extends-ing, the preset's paths (@site/*) resolve relative to the preset file location, so all @site/... aliases break. The child config must set baseUrl: "." to anchor to the project root (this is the official TS template's convention):
```
{
  "extends": "@docusaurus/tsconfig",
  "compilerOptions": {"baseUrl": "."},
  "include": ["src/", "docusaurus.config.ts", "sidebars.ts"]
}
```

Admonition syntax

When writing :::tip / :::note callouts, :::type must be on its own line followed by a blank line, with the title as :::type[Title]. Otherwise the whole block is treated as plain text and literal ::: shows up on the page.

5. Build & serve

npm run build      # production build, outputs to build/
npm run start      # dev server (hot reload), default http://localhost:3000/

On success:

[INFO] [en] Creating an optimized production build...
[SUCCESS] Generated static files in "build".

The dev server supports hot reload: editing markdown in docs/ or components refreshes the browser.
Changes to docusaurus.config.ts are not hot-reloaded — restart npm run start manually.
This is a long-running process; run it in the background or a dedicated terminal.

LAN access (optional)

npm run start -- --host 0.0.0.0

6. Access verification (docs-only routes)

Once the server is up, verify key routes:

curl -sS -o /dev/null -w '%{http_code}\n' http://localhost:3000/        # root → 200 (home doc)
curl -sS -o /dev/null -w '%{http_code}\n' http://localhost:3000/intro   # doc → 200
# /blog is disabled and returns Page Not Found

Open http://localhost:3000/ in a browser — seeing doc content means the whole chain works.

7. Common commands

Command	Purpose	Notes
`npm run start`	Dev server	Hot reload, daily writing
`npm run build`	Production build	Outputs to `build/`
`npm run serve`	Preview the build	Serves `build/` locally
`npm run typecheck`	TypeScript type-check	build doesn't type-check, run separately
`npm run clear`	Clear cache	First thing to try on weird build errors
`npm run deploy`	Deploy	Defaults to GitHub Pages

8. Directory structure

docusaurus-demo/
├── blog/                  # blog posts (markdown/mdx; disabled for now)
├── docs/                  # docs (this page lives here)
│   ├── getting-started.mdx   # slug: / → site home doc
│   ├── intro.mdx
│   ├── tutorial-basics/
│   └── tutorial-extras/
├── src/                   # custom pages, components, styles
│   ├── components/        # HomepageFeatures etc. (unused under docs-only, kept)
│   ├── css/
│   └── pages/
├── static/                # static assets (images), copied as-is
├── docusaurus.config.ts   # global config (title, URL, theme, docs-only, etc.)
├── sidebars.ts            # sidebar config (autogenerated)
├── tsconfig.json          # TypeScript config
├── package.json
└── README.md

Adding a new doc

The sidebar is auto-generated from the folder structure via {type: 'autogenerated', dirName: '.'} in sidebars.ts. Just create a new .md/.mdx under docs/ with frontmatter:

---
sidebar_position: 2
---

# My new doc

Body content...

No need to edit sidebars.ts — the new page appears in the sidebar automatically.

9. FAQ

Port 3000 in use

Start on another port:

npm run start -- --port 3001

Weird build errors

Clear the cache and retry:

npm run clear
npm run build

Config changes not taking effect

Restart npm run start manually after editing docusaurus.config.ts (config isn't hot-reloaded).

Build error: broken link / module not found

onBrokenLinks: 'throw' fails the build on any dead link. Under docs-only mode, update in-page /docs/xxx links to /xxx.

1. Prerequisites​

2. Initialize the project (TypeScript template)​

⚠️ About the interactive prompt​

3. Configure docs-only mode (root path shows docs directly)​

4. TypeScript type-checking​

Two pitfalls (from practice)​

5. Build & serve​

LAN access (optional)​

6. Access verification (docs-only routes)​

7. Common commands​

8. Directory structure​

Adding a new doc​

9. FAQ​