Publishing and Update Handbook
This page answers exactly two questions: how to update content and how to ship the site. Every step lists a command you can run and the result you should expect.
Prerequisite: Node.js 20 or newer (
node -vto confirm) and one successfulnpm installin the project root.
0. Two workflows at a glance
| What I want | Command | Time |
|---|---|---|
| Local preview with hot reload | npm start | ~20 s first run |
| Add a page | npm run new -- docs/<section>/<file>.md | instant |
| Self-check before committing | npm run check | instant |
| Build with every guard | npm run verify | 3–5 min |
| Build only | npm run build | 2–3 min |
| Inspect the build locally | npm run serve | instant |
One rule to remember: a green npm run verify means you may ship; a red one means do not.
1. Updating content
1.1 Adding a page
npm run new -- docs/ue/networking/my-topic.md
The script creates a file with complete frontmatter and touches no configuration. Sidebar, navigation, search index and sitemap all update themselves — that is the core promise of this template: adding content never requires editing code.
1.2 Every frontmatter field matters
---
title: Property Replication vs RPC
description: Starting from the bytes each actor costs per frame ... # summary for lists and SEO
sidebar_position: 1 # ordering among siblings, smaller is higher
tags: [Networking, Replication, Bandwidth]
subject_version: "5.8" # domain dimension, must exist in the configured list
updated: 2026-11-13 # last-updated date, strictly YYYY-MM-DD
access: free # free / member / pro; paid tiers are rejected at build time
---
When a field is missing or malformed, npm run check lists every problem:
frontmatter check passed: all fields present, access is free everywhere
1.3 Adding a section
A section is a folder; its name and order live in _category_.json inside that folder:
{
"label": "Networking",
"position": 3,
"link": {"type": "generated-index"},
"collapsible": true,
"collapsed": true
}
collapsed: true means collapsed by default — readers click the title to expand. The category containing the current page expands on its own, so nobody has to hunt for it. collapsible: true allows manual collapsing. Copy this block verbatim for new sections; false here leaves the whole sidebar expanded on first load.
You must also add the twin declaration under the English content directory, otherwise the English navbar entry is missing and npm run check:i18n fails:
i18n/en/docusaurus-plugin-content-docs/current/ue/networking/_category_.json
1.4 Bilingual is mandatory
This is the one hard obligation of the template. Every page under docs/ needs an English twin at the same path:
docs/ue/networking/my-topic.md
i18n/en/docusaurus-plugin-content-docs/current/ue/networking/my-topic.md
Three rules, all machine-checked:
| Check | Rule |
|---|---|
| File name | identical name and path |
| Body | no runs of Chinese (Chinese inside code spans and fences is exempt) |
| Routing fields | slug and sidebar_position must match the source |
npm run check:i18n
translation coverage: 9/9 pages (100%) | i18n/en JSON strings: 111
translation check passed: every page, category and UI string has a translation with no Chinese left
If you do not want to translate yet, keep that note outside docs/ (for example a root-level notes/ folder) so it is not treated as a page. Pages inside the site must be paired; this guard cannot be bypassed.
1.5 Editing an existing page
Edit both the docs/ file and its i18n/ twin. Two things to keep in sync:
- Bump
updated, otherwise the footer still shows the old date. - The commit message decides the changelog category (see 1.6).
1.6 The changelog is generated
Never edit docs/changelog/<year>.md by hand — it is regenerated wholesale and your edits will be overwritten.
npm run changelog # regenerate, writing both languages
npm run changelog:check # fail if a commit is not recorded yet (used in CI)
Classification comes from commit messages; a prefix overrides the default guess:
| Commit message | Category | When |
|---|---|---|
docs: add replication conditions | Added | new page |
fix: correct the quantisation figure | Revised | content change |
[勘误] correct callback thread claim | Correction | overturns a previous conclusion |
[破坏性更正] rewrite the queueing section | Breaking correction | an entire conclusion is obsolete |
Only the first two are inferred. Correction and breaking correction must be written by hand, because a machine cannot distinguish "adds detail" from "overturns". Those two are exactly what returning readers need to see.
1.7 Deleting or moving pages
| Action | What to do |
|---|---|
| Delete | remove both files, then npm run gen:index |
| Move / rename | move both; old links now 404. If the page was referenced externally, keep a slug pointing at the old URL |
| Reorder | change sidebar_position only; do not rename files |
Moving is the risky one: the file name is the URL. If a page has been shared, either keep an explicit slug for the old path or add a redirect plugin. Prefer the slug — zero dependencies.
1.8 Cutting a version snapshot
When the content is worth freezing (typically alongside an engine version):
npx docusaurus docs:version 5.8
This creates versions.json, versioned_docs/version-5.8/ and versioned_sidebars/. Afterwards:
currentkeeps evolving at the root path- the snapshot is pinned at
/5.8/and stops following the trunk - the navbar shows no version dropdown (deliberately disabled); reach snapshots by direct link. To bring the switcher back, add
{type: 'docsVersionDropdown', position: 'right'}tonavbarItemsindocusaurus.config.js
Note: snapshots do not receive later corrections. Either edit the snapshot files directly or publish a new minor version.
1.9 Swapping the entire content pack
Change only site.config.js and docs/; the template layer (src/, scripts/, docusaurus.config.js, sidebars.js) stays untouched. The full sequence is in Content Pack Checklist.
One trap worth repeating: the pack must include a page with slug: / at the docs root, otherwise the navbar "Home" link breaks and the build fails.
2. Building and shipping
2.1 Four things to do before launch
Skip these and the site opens, but search engines and shared links break:
| # | Item | Action | Cost of skipping |
|---|---|---|---|
| 1 | Set the real domain | build with SITE_URL=https://your-domain | canonical, sitemap, robots.txt and llms.txt all point at the placeholder example.com |
| 2 | Verify robots and sitemap | confirm build/robots.txt lists two sitemap entries | crawlers cannot find the sitemap |
| 3 | DNS and HTTPS | point the domain at the host, enable auto certificates | browsers flag the site as insecure |
| 4 | Replace footer and contacts | edit footer and links in site.config.js | shared links show template defaults |
SITE_URL is a build-time variable and must be passed on every build. What it affects:
canonical / hreflang -> docusaurus.config.js
sitemap.xml (two files) -> generated during build
robots.txt -> scripts/gen-site-meta.mjs
llms.txt -> scripts/gen-site-meta.mjs
2.2 One command to build
SITE_URL=https://docs.your-domain.com npm run verify
On Windows PowerShell:
$env:SITE_URL="https://docs.your-domain.com"; npm run verify
verify runs six gates in order and stops at the first failure, so you never get a half-built artefact:
| Order | Gate | What it blocks |
|---|---|---|
| 1 | check-template-purity | domain words leaking into the template layer |
| 2 | changelog:check | commits missing from the changelog |
| 3 | check-frontmatter | missing fields, non-free access, unknown version values |
| 4 | check-i18n | missing translations, Chinese left in English, missing category twins |
| 5 | gen-search-index | builds the search index |
| 6 | gen-site-meta + docusaurus build | generates robots/llms, compiles the site |
Success looks like two SUCCESS lines at the end, one per locale.
2.3 What the build contains
build/
├── index.html Chinese home
├── 404.html
├── robots.txt <- generated, never edit by hand
├── llms.txt <- summary for AI crawlers
├── search-index.json <- local search index
├── sitemap.xml Chinese, ~42 URLs
├── en/
│ ├── index.html English home
│ ├── sitemap.xml English, ~42 URLs
│ └── ...
├── ue/… conventions/… changelog/… ops/…
└── assets/ hashed js and css
build/ is the whole site: pure static, no server dependency. Upload it and you are live.
2.4 Hosting options
Option A: Nginx (own server)
server {
listen 80;
server_name docs.your-domain.com;
root /var/www/docs-ue/build;
index index.html;
# hashed assets: cache hard
location /assets/ {
expires 1y;
add_header Cache-Control "public, immutable";
}
# HTML: short cache so updates appear quickly
location ~* \.html$ {
expires 5m;
add_header Cache-Control "public, must-revalidate";
}
# directory-style routing: /ue/networking/foo -> /ue/networking/foo/index.html
location / {
try_files $uri $uri/ $uri/index.html =404;
}
error_page 404 /404.html;
}
The try_files line is not optional; without it every subpage returns 404, because Docusaurus emits directory-style routes.
Option B: Vercel or Netlify (zero maintenance, recommended)
| Setting | Value |
|---|---|
| Build command | SITE_URL=https://docs.your-domain.com npm run verify |
| Output directory | build |
| Node version | 20 |
| Environment variable | SITE_URL = production domain |
Both handle HTTPS and directory routing automatically.
Option C: Object storage + CDN
- Upload the whole
build/folder, preserving the directory structure - Set the index document to
index.htmland the error document to404.html - Critical: enable "sub-directory index document", otherwise
/ue/foo/cannot open - CDN cache: one year for
/assets/*, five minutes for/*.html
2.5 Post-launch verification
Do not stop at "the home page loads". All six checks below must pass:
curl -I https://docs.your-domain.com/
curl -I https://docs.your-domain.com/robots.txt
curl -I https://docs.your-domain.com/en/
curl -I https://docs.your-domain.com/sitemap.xml
curl -I https://docs.your-domain.com/en/sitemap.xml
curl -s https://docs.your-domain.com/robots.txt
| Check | Expectation |
|---|---|
| Home page | 200 with content-type: text/html |
/robots.txt | 200, containing two Sitemap: lines with the real domain |
/en/ | 200, page language English |
| Both sitemaps | 200, roughly 42 entries each |
| Three random inner pages | 200, sidebar highlights correctly |
| Mobile width | navbar shows a search icon that opens and returns results |
Finally, view the page source and confirm canonical is the real domain. If it still says example.com, SITE_URL did not take effect during the build.
2.6 Rolling back
Rolling back a static site means restoring the previous artefact:
| Setup | How |
|---|---|
| Vercel / Netlify | pick the previous deployment in the dashboard, one click |
| Own server | keep the previous directory and switch a symlink with ln -sfn |
| Object storage | enable versioning and restore a previous version |
Recommendation: keep the last three builds in timestamped folders (releases/2026-11-13-1800/) and switch a symlink on failure — recovery in seconds.
3. Pre-launch checklist
Do not publish until every box is ticked.
-
SITE_URLset to the production domain;canonicalcorrect after build -
build/robots.txtcontains twoSitemap:lines - Three pages spot-checked in each language, content and sidebar correct
-
npm run verifyfully green (six gates plus twoSUCCESSlines) - Search works in the navbar at mobile width
- Footer contacts, filing number and copyright year replaced with real values
- HTTPS certificate valid, http redirects to https
- 404 page renders for a non-existent path
- Site is crawlable:
curl -A "Googlebot" https://domain/returns 200, not a login wall - The current build is backed up
"Crawlable" matters beyond SEO: applying for Algolia full-text search later requires that the whole site can be crawled first.
4. Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Every subpage 404s, home works | host lacks directory routing | add try_files, or enable sub-directory index documents |
Build fails with Broken link | a link points nowhere; a swapped content pack lacks the slug: / page | fix the reported path, or add the guide page |
Subject.field is not declared | site.config.js lost subject.field | restore it; the guard derives the frontmatter field name from it |
| English pages show Chinese | translation file missing, framework falls back silently | run npm run check:i18n |
| New page is not searchable | index not rebuilt | npm run gen:index; under dev it rebuilds itself |
| Changelog reports unrecorded commits | not regenerated after committing | npm run changelog, then commit |
Build hangs in docusaurus build | out of memory, or a broken link | read the first Error in the log |
| Styling broken, CSS seemingly absent | baseUrl does not match the deploy path | adjust baseUrl in docusaurus.config.js |
A general rule: when a build fails, read the first error in the log. Everything after it is usually fallout.
5. In one line
Content update = write the file + add the English twin + run npm run check; shipping = npm run verify with SITE_URL set + upload build/.
Everything else — sidebar, search index, sitemap, robots, changelog, bilingual routing — is handled by scripts. None of it needs manual maintenance.