Districts Documentation

Documentation site for Districts, served at https://docs.districts.xyz/districts/.

Built with Docusaurus 2. Migrated from GitBook.

Local development

npm install
npm start          # dev server
npm run build      # production build into ./build
npm run serve      # serve the production build locally

Deployment

Pushes to main build a container image and pin its tag in the gitops repo at districts-docs/overlays/prod/deployment.yaml, which ArgoCD syncs to the prod cluster. See .github/workflows/prod.yaml.

The site is served by nginx under the /districts/ path to match the URLs the GitBook site used, so baseUrl in docusaurus.config.js and the location block in conf/conf.d/default.conf must stay in agreement.

Importing content from GitBook

GitBook Git Sync pushes the space to the migration branch of this repo. scripts/gitbook-import.py converts that export into the docs/ tree.

git worktree add ../gitbook-export migration
python3 scripts/gitbook-import.py --source ../gitbook-export

Re-running is safe — it rewrites docs/, sidebars.generated.json and static/gitbook/assets/ from the export each time, so local edits to those belong in GitBook instead.

SUMMARY.md is the source of truth for structure. Its ## HEADING blocks become the sidebar groups and its nested list items the page order and labels; the directory layout does not encode the grouping, since Introduction lives at the export root but belongs to the GENERAL group. That is why the sidebar is generated rather than autogenerated from the filesystem.

The importer also:

• turns <table data-view="cards"> into a card grid, since the export writes card covers and targets as anchors whose text is a filename
• converts {% embed %} of a video into a <video> element and {% hint %} into an admonition
• rewrites .gitbook/assets/ references, copying only the assets actually referenced (the export carries a large number of unreferenced uploads)
• rewrites .md hrefs in raw HTML to real routes, which Docusaurus does not do for anything outside markdown link syntax
• self-closes void tags, because MDX parses JSX and a bare <img> fails the build
• reports anything it could not resolve rather than emitting a dead link