refactor: migrate from Astro Starlight to Docusaurus and refactor hosting system#13
Merged
Conversation
Three issues prevented Docusaurus 3.10.2 from building on Node.js 22:
1. require.resolveWeak not defined — polyfilled as no-op in ssgNodeRequire
2. Externalized ESM theme files importing @theme/* aliases and .css files fail
in the SSG eval context — caught and returned as empty modules
3. webpack CJS chunks treated as ESM due to project-level "type":"module" —
fixed by writing {"type":"commonjs"} into the server output dir before eval
…e tunnel Adds a full docs/ section for the trickfire-docs framework itself, served at /trickfire-docs/ on the live site. Covers architecture, member guide, writing content, sidebar config, configuration reference, and deployment. Deployment docs describe the Cloudflare tunnel setup instead of direct TLS, so the nginx config is simplified (localhost:80 only, no certbot needed).
Three root causes fixed: 1. Preset resolution: generated docusaurus.config.js used the bare package name "@docusaurus/preset-classic", which Docusaurus resolves via createRequire(siteConfigPath) — that require never reaches trickfire-docs's node_modules. Fix: resolve the preset to an absolute path at config- generation time using createRequire(import.meta.url) inside generate.ts. 2. React/react-dom/@mdx-js symlinks: ensureSiteNodeModules was symlinking into .trickfire/node_modules/, but Docusaurus's resolveSitePkg() uses siteDir (= cwd) not the config file dir. Symlinks must go in projectRoot/node_modules/. 3. Dangling symlinks: pnpm hoists nothing to node_modules/react — the actual path is node_modules/.pnpm/react@x/node_modules/react. Fix: resolve package dirs via _require.resolve() rather than constructing guessed paths. Added ./package.json-less fallback (walk up from main entry) for packages like @mdx-js/react that don't export that subpath. Also adds scaffold/.npmrc (shamefully-hoist=true) so pnpm member repos hoist Docusaurus peer deps, and fixes generate.ts to use absolute paths for all file references so the config works from .trickfire/ as the site root dir.
Raw `Cannot find module` from jiti was confusing. Now shows a clear message pointing to `trickfire-docs init` (member repos) or `pnpm website:dev` (the trickfire-docs repo itself).
…auto When the member repo has "type":"module" in its package.json, webpack treats all .js files as ESM. Docusaurus's generated client-modules.js and routes.js use mixed ESM/CJS syntax (export default + require()), which ESM mode rejects. Extend the @docusaurus/core patch: generateSiteFiles now writes an empty package.json (no "type" field) into .docusaurus/ before generating any files. Webpack then uses javascript/auto for files in that directory, which supports the mixed ESM/CJS pattern Docusaurus has always generated.
Using --config with a named file (trickfire-docs.yml instead of config.yml) makes cloudflared register the service as cloudflared-trickfire-docs rather than the generic cloudflared, so multiple tunnels can coexist on the same server without conflicts.
…vice The --config flag does not affect the unit name. To get a named service (cloudflared-trickfire-docs) the unit file must be written manually. Replace the service install command with a tee + systemd approach.
- docs/deployment/index.md: fill in GitHub Runner TODO section - deploy.yml: add docs/** and docs-sidebars.js to path triggers so changes to the framework's own docs redeploy the site - CONTRIBUTING.md: remove dead link to README#releasing section - test-cli.sh: switch npm/npx to pnpm
matejstastny
changed the title
|
🎉 This PR is included in version 1.3.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
trickfire-docsCLInpmproject initialized in them, just thedocs/folder and thedocs.config.tsconfig filenpxusingnpx trickfire-docs initandnpx trickfire-docs devfor testing the pagesHosted site
docs.trickfirerobotics.comserves all member docs under one roofsync-docs.ymlworkflow that rsyncs theirdocs/intocontent/<repo-name>/on the server and triggers a rebuildTrickFireRobotics.github.io(done to make the deployment of multiple repos to one domain without changing the org-wide domain possible)Migration from Astro Starlight to Docusaurus
Cloudflare tunnel
nginxlistens onlocalhost:80only, with no TLS cert.cloudflared(service:cloudflared-trickfire-docs) opens an outbound tunnel to Cloudflare, which terminates HTTPS and proxies traffic tonginx@docusaurus/corepatch"type":"module"projects:require.resolveWeakin the SSG eval context{"type":"commonjs"}next to the server bundle so Node.js doesn't treat webpack CJS chunks as ESM{}into.docusaurus/so webpack usesjavascript/automode for Docusaurus's generated files (which mixexport defaultwithrequire())Framework docs
/trickfire-docs/: member guide, architecture overview, configuration reference, content writing guide, and deployment guides for the server, Cloudflare tunnel, and GitHub Actions runner