Skip to main content

Server Onboarding Notion to Docusaurus Migration Report (2026-02-15)

This report summarizes the migration work performed from Notion export into Docusaurus for the Linux Server onboarding knowledge base.

1. Objective​

  • Audit and normalize all onboarding .mdx files before migration.
  • Reorganize content into a category-based folder structure.
  • Move finalized content into Docusaurus docs and make it visible in sidebar/navigation.
  • Resolve build/runtime failures observed during rollout.

2. Source and Destination​

ItemPath
Notion-export source/home/rezriz/notion-export-to-docusaurus/linux-server-notion-to-brain/vps-ubuntu-for-managing-wordpress/00-server-onboarding
Docusaurus target/opt/docker-data/apps/docusaurus/site/docs/server/linux-server/01. Server-onboarding
Docs config/opt/docker-data/apps/docusaurus/site/sidebars.js
Site config/opt/docker-data/apps/docusaurus/site/docusaurus.config.js

3. Migration Work Executed​

3.1 MDX readiness audit and normalization​

  • Audited all .mdx files in source onboarding folder.
  • Fixed malformed frontmatter delimiters.
  • Removed accidental outer code-fence wrappers around full documents.
  • Removed stray trailing code fences causing parse errors.
  • Normalized problematic filenames (spaces, parentheses, case collisions, numeric suffixes where needed).

3.2 Content structure reorganization​

  • Reorganized onboarding docs into:
    • shared-core
    • wordpress
  • Removed saas-docker from onboarding scope (dedicated Docker knowledge base exists elsewhere).
  • Generated _category_.json recursively for folders.
  • Added explicit category position and label ordering for shared-core and nested sections.

3.3 Content quality updates​

  • Rewrote pages with mismatched title/content intent:
    • ip-root-password-ssh.mdx
    • timdedatectl.mdx
  • Split SSH hardening section into two subcategories:
    • step
    • knowledge
  • Reclassified SSH docs by intent and moved files accordingly.

4. Deployment into Docusaurus​

  • Replaced destination folder content at:
    • docs/server/linux-server/01. Server-onboarding
  • Updated navigation/sidebar exposure:
    • Added onboarding sidebar entry in sidebars.js
    • Added Server Onboarding menu linkage in docusaurus.config.js

5. Issues Encountered and Fixes Applied​

Issue A: MDX compile failures​

Symptoms:

  • parser errors (unexpected-eof)
  • unresolved local image links

Fixes:

  • corrected malformed table markup in ufw-overview.mdx
  • removed missing image references in move-wpconfigphp-to-upper-folder.mdx
  • added missing MDX component imports (Tabs, TabItem) where required

Symptoms:

  • Should have a queue React runtime error
  • trace pointed to @easyops-cn/docusaurus-search-local

Fixes:

  • disabled search plugin configuration
  • removed local search package dependency
  • cleared generated cache and restarted service

Issue C: ChunkLoadError in browser​

Symptoms:

  • repeated failed chunk requests (__props---..., content---...)

Causes:

  • stale browser/session chunk references after rebuild
  • Cloudflare Access returning HTML for stale JS requests

Fixes:

  • rebuilt static assets
  • normalized container runtime mode
  • required hard refresh/session reset/cache purge on client side

Issue D: High CPU and memory usage​

Symptoms:

  • docusaurus container consumed high CPU and multi-GB memory

Cause:

  • public service was running in dev mode (docusaurus start)

Fix:

  • switched production runtime to static serving mode (docusaurus serve)
  • kept dev mode available only for authoring workflow when needed

6. Result​

  • Onboarding docs migrated and reorganized in Docusaurus structure.
  • Sidebar/category organization applied and improved.
  • Build-blocking MDX errors resolved.
  • Runtime/plugin instability mitigated.
  • Resource usage reduced substantially after switching to static serve mode.

7. Operational Guidance Going Forward​

Current runtime behavior:

  • start script uses docusaurus build && docusaurus serve.
  • A container restart will rebuild static assets first, then serve production output.

Estimated update time after content changes:

  • Small edits (1-3 files): about 30-90 seconds
  • Medium edits (5-20 files): about 1-3 minutes
  • Large refactors (many files/categories): about 3-6 minutes

Recommended procedure for publishing updates:

  1. Save content changes in docs/....
  2. Restart Docusaurus container.
sudo docker restart docusaurus
  1. Watch logs until serve is ready.
sudo docker logs -f docusaurus

Wait for:

[SUCCESS] Serving "build" directory at: http://0.0.0.0:3000/
  1. Hard refresh browser (Ctrl+Shift+R).
  2. If stale chunks remain, re-auth Cloudflare Access and purge cache.

Manual fallback (if restart build is interrupted):

sudo docker exec -w /app docusaurus npm run build
sudo docker restart docusaurus

Use dev mode only for temporary authoring/preview windows, not as public runtime.

  • docs/knowledge/docusaurus/10. Troubleshooting/troubleshooting-server-onboarding-runtime-and-performance-incident.mdx