Skip to main content
Version: Next

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 -v to confirm) and one successful npm install in the project root.

0. Two workflows at a glance​

What I wantCommandTime
Local preview with hot reloadnpm start~20 s first run
Add a pagenpm run new -- docs/<section>/<file>.mdinstant
Self-check before committingnpm run checkinstant
Build with every guardnpm run verify3–5 min
Build onlynpm run build2–3 min
Inspect the build locallynpm run serveinstant

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:

CheckRule
File nameidentical name and path
Bodyno runs of Chinese (Chinese inside code spans and fences is exempt)
Routing fieldsslug 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:

  1. Bump updated, otherwise the footer still shows the old date.
  2. 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 messageCategoryWhen
docs: add replication conditionsAddednew page
fix: correct the quantisation figureRevisedcontent change
[勘误] correct callback thread claimCorrectionoverturns a previous conclusion
[破坏性更正] rewrite the queueing sectionBreaking correctionan 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​

ActionWhat to do
Deleteremove both files, then npm run gen:index
Move / renamemove both; old links now 404. If the page was referenced externally, keep a slug pointing at the old URL
Reorderchange 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:

  • current keeps 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'} to navbarItems in docusaurus.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:

#ItemActionCost of skipping
1Set the real domainbuild with SITE_URL=https://your-domaincanonical, sitemap, robots.txt and llms.txt all point at the placeholder example.com
2Verify robots and sitemapconfirm build/robots.txt lists two sitemap entriescrawlers cannot find the sitemap
3DNS and HTTPSpoint the domain at the host, enable auto certificatesbrowsers flag the site as insecure
4Replace footer and contactsedit footer and links in site.config.jsshared 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:

OrderGateWhat it blocks
1check-template-puritydomain words leaking into the template layer
2changelog:checkcommits missing from the changelog
3check-frontmattermissing fields, non-free access, unknown version values
4check-i18nmissing translations, Chinese left in English, missing category twins
5gen-search-indexbuilds the search index
6gen-site-meta + docusaurus buildgenerates 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)

SettingValue
Build commandSITE_URL=https://docs.your-domain.com npm run verify
Output directorybuild
Node version20
Environment variableSITE_URL = production domain

Both handle HTTPS and directory routing automatically.

Option C: Object storage + CDN

  1. Upload the whole build/ folder, preserving the directory structure
  2. Set the index document to index.html and the error document to 404.html
  3. Critical: enable "sub-directory index document", otherwise /ue/foo/ cannot open
  4. 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
CheckExpectation
Home page200 with content-type: text/html
/robots.txt200, containing two Sitemap: lines with the real domain
/en/200, page language English
Both sitemaps200, roughly 42 entries each
Three random inner pages200, sidebar highlights correctly
Mobile widthnavbar 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:

SetupHow
Vercel / Netlifypick the previous deployment in the dashboard, one click
Own serverkeep the previous directory and switch a symlink with ln -sfn
Object storageenable 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_URL set to the production domain; canonical correct after build
  • build/robots.txt contains two Sitemap: lines
  • Three pages spot-checked in each language, content and sidebar correct
  • npm run verify fully green (six gates plus two SUCCESS lines)
  • 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​

SymptomCauseFix
Every subpage 404s, home workshost lacks directory routingadd try_files, or enable sub-directory index documents
Build fails with Broken linka link points nowhere; a swapped content pack lacks the slug: / pagefix the reported path, or add the guide page
Subject.field is not declaredsite.config.js lost subject.fieldrestore it; the guard derives the frontmatter field name from it
English pages show Chinesetranslation file missing, framework falls back silentlyrun npm run check:i18n
New page is not searchableindex not rebuiltnpm run gen:index; under dev it rebuilds itself
Changelog reports unrecorded commitsnot regenerated after committingnpm run changelog, then commit
Build hangs in docusaurus buildout of memory, or a broken linkread the first Error in the log
Styling broken, CSS seemingly absentbaseUrl does not match the deploy pathadjust 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.