Architecture
The site is a small consumer overlay on a shared Docusaurus container image. This keeps shared theme and build behavior centralized while allowing the blog to own its content, routes, and deployment settings.
Route Ownership
| Route | Source | Ownership |
|---|---|---|
/ | JournalHome.tsx and generated post metadata | Journal discovery home |
/journal/ | JournalDiscovery/Journal.tsx | Searchable publication-order index |
/chronicles/ | journal.config.json and curated hub pages | Connected reading paths |
/projects/ | JournalDiscovery/index.tsx | Game Engine and Neo project directory |
/<slug>/ | Markdown under docs/blog/ | Authored blog post |
/archive/ | Docusaurus blog archive | Chronological discovery |
/tags/ | tags.yml and journal.config.json | Topics grouped by subject |
/tags/<tag-permalink>/ | Post front matter and docs/blog/tags.yml | Tagged-post discovery |
/rss.xml, /atom.xml | Docusaurus production build | Syndication feeds |
/blog/** | Pages under docs/src/pages/blog/ | Legacy-route compatibility |
/docs/ | docs/docs/index.md | Generated documentation landing page |
/docs/** | Markdown under docs/docs/ | Authored project documentation |
The local docs/plugins/journal-discovery.cjs plugin derives discovery data from
Docusaurus post metadata. docs/journal.config.json owns presentation groups,
Chronicle starting points, and compatibility indexes for retired tags. Topic
groups add no required post fields. Curated hub entries remain in their page
source under docs/src/pages/.
Build Boundary
The docs/ directory is copied over the shared template during a build.
Repository files can configure Docusaurus and add content, but shared
components, theme behavior, and build scripts remain owned by the
Docusaurus Template.
Both local build references pin the same immutable container digest:
docs/Dockerfiledocs.ps1
CI does not use that image: .github/workflows/docs.yml calls the shared
docs.yml reusable workflow from The-Running-Dev/GitHub-ActionTemplates,
which builds on its own pinned build-agent image.
Delivery
Pull requests run the documentation gate and a production build. A push to
main builds the same overlay and deploys the resulting static artifact to
GitHub Pages at the custom domain.
After each production build, build/Test-DocumentationArtifact.ps1 verifies
the canonical routes, compatibility pages, archive, predefined tag pages, and
RSS and Atom feeds before the artifact can be uploaded.
The compatibility pages under /blog/ emit an HTML meta refresh for clients
without JavaScript, repeat the redirect after hydration, and retain a visible
fallback link. Keep them while previously published links may still be in use.