Conversation
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ❌ Deployment failed View logs |
cardano-db-sync-docs | a18e651 | Sep 14 2026, 08:51 AM |
profd2004
marked this pull request as ready for review
September 14, 2026 11:52
Replaces the removed Astro project with a Docusaurus 3 workspace under docs/: npm scripts for the two build profiles, TypeScript in strict mode, eslint, prettier and vitest with coverage thresholds. Refs B01.
config/profiles.ts is the single origin for every environment-dependent value. The developer profile publishes the fork to /cardano-db-sync/ against preview; production publishes at / against mainnet. resolveProfile() throws rather than defaulting, so a build cannot silently pick the wrong one (ENV-1). The CNAME plugin writes the Pages CNAME from the profile in postBuild, and removes a stray one on the developer profile, so the fork's site can never be sent to production's host (ENV-6). markdown.format is deliberately left unset, which keeps Docusaurus at its mdx default; a unit test fails if a format key appears in the config (CON-9). Refs B01.
npm run check:baseurl walks the source, config and authored content and fails on a developer baseUrl, a production host, or baseUrl assigned a string literal outside config/profiles.ts. A GitHub repository URL legitimately contains the repository name, so it is exempted before the rules run; eslint carries the same rule for TypeScript sources. Refs B01, ENV-1.
Builds both profiles back to back from one working tree, asserts the developer output carries no CNAME and production's holds the host, checks baseUrl reaches the emitted HTML under both, and confirms a build succeeds with only DOCS_PROFILE in the environment (ENV-5). The Markdown gate test writes a file MDX cannot compile and requires the build to fail. Its filename must not start with an underscore: Docusaurus treats _*.md as a partial and excludes it, which made the first version of this test pass against a build that had never read the file. Refs B01.
Two jobs on changes under docs/: format, lint, types, the ENV-1 gate and unit tests; then both build profiles with the CNAME and Markdown-gate assertions. Refs B01.
…nsole tsc --noEmit passed here and failed in CI on the same commit: inference took the parameter type from the `console` default, and the two environments resolved a different `Console`. An explicit @typedef removes the dependence on inference, so the contract is the two methods the gate actually calls. Refs B01.
The gate guarded the production host but not the developer one, so a hardcoded https://lidonation.github.io would have passed. Same class of value, now the same rule. organizationName and projectName were pinned to upstream. They are environment-dependent for the same reason repoUrl is, so they come from the profile. engines said node >=20.0, but the gate script uses import.meta.dirname, which landed in 20.11. Refs B01, ENV-1.
profd2004
force-pushed
the
feat/b01-docusaurus-scaffold
branch
from
September 17, 2026 16:10
a18e651 to
747627a
Compare
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.
Summary
The big idea is to put a Docusaurus skeleton in
docs/that builds two sites from one codebase: the fork's dev site under/cardano-db-sync/against Cardano preview, and production at/fordbsync.cardano.intersect.orgagainst mainnet. Everything in Phases 0 to 3 gets built inside this skeleton, so it goes in first.The environment lives in exactly one file,
docs/config/profiles.ts.DOCS_PROFILE=dev|prodpicks a profile andresolveProfile()throws if it is missing or unknown, so a build cannot quietly choose one for you. The config, the CNAME plugin and the pages all read from the profile, andnpm run check:baseurlwalks the tree and fails on any environment literal that escaped it.No design system here. The token pipeline is B42 and the drawn UI is B47, and KICKOFF §3 says not to invent a colour or a spacing value, so
custom.cssis empty and the landing page is plain HTML with a link.Refs
Refs #2 (checklist item B01).
Traceability
baseUrlis a variable at every use site, no hardcoded value outside the profile moduletest/unit/profiles.test.ts,test/unit/config.test.ts,test/unit/check-baseurl.test.ts,test/build/profiles.test.tsd68c4853,2b9187a9,a18e6517CNAMEis emitted for production only; dev output carries nonetest/unit/cname.test.ts,test/build/profiles.test.tsd68c4853,26c74192markdown.formatstays at themdxdefault, asserted and marked do-not-changetest/unit/config.test.tsd68c4853test/build/profiles.test.ts26c74192test/build/markdown-gate.test.ts26c74192tsc --noEmitclean, unit tested with coveragenpm run verify81014c09,8d4f807c,4d95b714test/build/profiles.test.ts26c74192Decisions
repoUrl,organizationNameandprojectNameare part of the profile. The edit-this-page link and the navbar GitHub link point at the fork on dev and at upstream on production. Same reasoning asbaseUrl: the repository is environment-dependent, so it belongs in the profile, not in the config.resolveProfile()throws instead of defaulting. A default is how a dev build ends up publishing to production's host. The npm scripts set the variable throughcross-env, so nobody meets the error in normal use.github.com/<org>/cardano-db-sync/...contains the repo name and none of those is abaseUrl. Content will link to the repository constantly, so the gate strips that URL from a line before the rules see it, and there is a test proving a realbaseUrlon the same line is still caught./. Withblog: falseand docs under/docs, the root had no route and the broken-link check failed the build - correctly. The page is a React page undersrc/pages/per CON-11, with no invented visual values.Assumptions
docs-rebuild-specon this fork, notmaster.masterstill carries the Astro site and has no SPECIFICATION.md, so it is not a base this can sit on.doc/is untouched (D3) anddocs/docs/holds one seed page to prove the pipeline.Blockers
None.
Verification
Run from
docs/:Locally, on Node 24:
npm run format:check- cleannpm run lint- cleannpm run typecheck- cleannpm run check:baseurl- cleannpm test- 52 tests, coverage 99.31% lines / 100% functionsnpm run test:build- 10 tests, both profiles built back to back from one treeTwo things the build tests check that a property dump would not:
build/dev/has noCNAMEandbuild/prod/CNAMEreadsdbsync.cardano.intersect.org, and the dev HTML resolves assets through/cardano-db-sync/assets/while production resolves them through/assets/.Three findings from the review pass that are worth naming, because all three would have shipped as silent passes:
__broken-markdown-fixture.md. Docusaurus treats a_-prefixed file as a partial and excludes it, so the build never read the file and the test proved nothing. Renamed, and the test now also asserts the fixture name appears in the failure output.tsc --noEmitpassed locally and failed in CI on the same commit. The gate's reporter parameter was inferred from itsconsoledefault and the two environments resolved a differentConsoletype. It is an explicit@typedefnow.https://lidonation.github.iowould have passed it.Manual pipeline jobs a human still needs to trigger: none. The repo's existing Haskell CI runs on every push with no path filter, so it is also running on this docs-only branch; it is unrelated to this change.
Progress
url,baseUrlandCNAME