canton-network · hrischuk-da · Sep 9, 2026 · Sep 8, 2026 · Sep 8, 2026 · Sep 8, 2026
diff --git a/.github/workflows/mintlify-validate.yml b/.github/workflows/mintlify-validate.yml
@@ -27,18 +27,23 @@ jobs:
       - name: Validate external snippet wrapper
         run: nix-shell --run 'npm run test:external-snippets'
 
-      - name: Validate generated-reference history output
+      - name: Validate generated-reference output
         run: >-
           nix-shell --run 'python3 -m pytest
           tests/test_history_contract.py
           tests/test_reference_page_history.py
           tests/test_openapi_manual_render.py
-          tests/test_json_api_openapi.py'
+          tests/test_json_api_openapi.py
+          tests/test_canton_topology_transaction_versions.py'
 
       - name: Check JSON Ledger OpenAPI generated output
         run: >-
           nix-shell --run 'python3 scripts/generate_json_api_reference.py &&
+          npm run build &&
           git diff --exit-code --
+          docs-source/docs.json
+          docs-source/openapi/json-ledger-api/openapi.yaml
+          docs-source/reference/json-api-reference
           docs-main/docs.json
           docs-main/openapi/json-ledger-api/openapi.yaml
           docs-main/reference/json-api-reference'

diff --git a/.github/workflows/pull-external-snippets.yml b/.github/workflows/pull-external-snippets.yml
@@ -54,15 +54,25 @@ jobs:
         uses: actions/download-artifact@v5
         with:
           artifact-ids: ${{ env.artifact_id }}
-          path: snippets/external/${{ env.repo_name }}/${{ env.repo_version }}
+          path: docs-source/snippets/external/${{ env.repo_name }}/${{ env.repo_version }}
           github-token: ${{ env.external_token }}
           repository: ${{ env.repo_org }}/${{ env.repo_name }}
           run-id: ${{ env.run_id }}
+      - name: Set up Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: 24
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+      - name: Render documentation
+        run: npm run build
       - name: Create Pull Request
         uses: peter-evans/create-pull-request@v8
         with:
           branch: external-snippet-update-${{ env.repo_name }}-${{ env.repo_version }}
           base: main
           token: ${{ secrets.DOCS_PR_TOKEN }}
           title: External Snippet updates ${{ env.repo_name }} (${{ env.repo_version }}) [${{ env.trigger_sha_short }}]
-          commit-message: External Snippet updates ${{ env.repo_name }} (${{ env.repo_version }}) [${{ env.trigger_sha_short }}]
+          commit-message: External Snippet updates ${{ env.repo_name }} (${{ env.repo_version }}) [${{ env.trigger_sha_short }}]
diff --git a/.github/workflows/validate-network-variable-tabs.yml b/.github/workflows/validate-network-variable-tabs.yml
@@ -23,5 +23,11 @@ jobs:
         with:
           python-version: "3.14"
 
+      - name: Test corpus rendering and source edit links
+        run: |
+          python3 -m pip install pytest
+          python3 -m pytest tests/test_network_variable_tabs.py tests/test_update_generated_reference_prs.py tests/test_generate_external_snippets.py
+          node --test tests/test_edit_source.cjs
+
       - name: Validate rendered network variable tabs
         run: npm run validate:network-variable-tabs
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -69,7 +69,7 @@ OR:
 
 ```bash
 direnv allow
-cd docs-main && mintlify dev
+npm run dev
 ```
 
 The site will be available at <http://localhost:3000>.
@@ -88,7 +88,7 @@ Open a PR there to add your tool. Maintaining external tooling in the Dev Hub en
 
 ## Content and style guidelines
 
-- Match the tone and structure of the surrounding pages in `docs-main/` don't introduce a new voice or format for a single page.
+- Match the tone and structure of the surrounding pages in `docs-source/` don't introduce a new voice or format for a single page.
 
 - Prefer editing an existing page over creating a new one if the topic already has a home.
 
@@ -115,3 +115,10 @@ By contributing, you agree your changes are licensed under this repo's license m
 - Once approved and checks pass, the docs team merges.
 
 Questions about where something belongs, or whether a change is worth making? Open a [Discussion](https://github.com/canton-network/cf-docs/discussions) before doing the work.
+
+## Source and generated output
+
+Make changes in `docs-source/`, then run `npm run build` and
+`npm run validate:network-variable-tabs`. Commit the source changes and their
+`docs-main/` output together. See the [source workflow](README.md#source-and-published-output)
+for authoring network-variable blocks and running upstream generators.
diff --git a/README.md b/README.md
@@ -49,11 +49,58 @@ OR:
 - [Node.js 24](https://nodejs.org/en/download) (note that `mintlify` is not currently compatible with Node.js 26)
 - [Python 3.14](https://www.python.org/downloads/) if you are running any of the machinery for syncing snippets or updating generated docs
 
+### Source and published output
+
+Edit the complete documentation corpus in `docs-source/`, including pages,
+`docs.json`, snippets, images, scripts, and API specifications. `docs-main/` is
+checked-in output and remains Mintlify's deployment directory. Never edit output
+directly: generation overwrites it and removes files deleted from source.
+
+```bash
+npm run build
+npm run validate:network-variable-tabs
+```
+
+Commit both trees together. The existing network-variable check now verifies
+**every output file**, including ordinary pages and binary assets. It detects
+missing, extra, or changed targets without modifying either tree.
+
+When rebasing an existing branch, move its documentation edits and generator
+destinations from `docs-main/` to `docs-source/` before rebuilding. Automation
+must generate source, run the build, and include both trees in its commit paths.
+Validators and previews that read published output continue to use `docs-main/`.
+External snippet identifiers and `/snippets/...` imports keep their existing names.
+
+Author network-dependent content inline in a source page:
+
+```mdx
+<NetworkVariables>
+
+Scan URL: |gsf_scan_url|
+
+</NetworkVariables>
+```
+
+The build expands these blocks to static DevNet, TestNet, and MainNet tabs using
+`docs-source/snippets/generated/version-dashboard-data.mdx`. Import snippet
+components at the top of the page as usual; imports used inside a block are
+inlined before substitution. The previous `snippets/networkvars/` fragments have
+been incorporated into their owning source pages. The old `--bootstrap` migration
+option is no longer needed.
+
+“Suggest edits” opens the matching file in `docs-source/`. `edit-source.js`
+redirects Mintlify's generated GitHub edit links, preserving the selected branch
+and filename even when the footer appears after consent or client navigation.
+
+Reference, release-note, dashboard, and snippet generators now write to
+`docs-source/`. After running one manually, run `npm run build` and commit both
+trees. The generated-docs PR automation performs these steps together.
+
 ### Running the dev server
 
 ```bash
 direnv allow
-cd docs-main && mintlify dev
+npm run dev
 ```
 
 The site will be available at http://localhost:3000.
@@ -66,7 +113,7 @@ mintlify broken-links
 
 ## Generate external snippets
 
-External snippet extraction from source repositories is documented in [config/snippet-config/update-workflows.md](config/snippet-config/update-workflows.md). Use that workflow when updating snippet configs under `config/snippet-config/` or regenerating checked-in snippets under `docs-main/snippets/external/`.
+External snippet extraction from source repositories is documented in [config/snippet-config/update-workflows.md](config/snippet-config/update-workflows.md). Use that workflow when updating snippet configs under `config/snippet-config/` or regenerating checked-in snippets under `docs-source/snippets/external/`.
 
 Run this whenever you add, remove, or update a snippet source in `config/snippet-config/`, or when you need to pull in changes from an upstream repo (such as Canton or Splice) that are referenced by existing snippets.
 

diff --git a/config/snippet-config/update-workflows.md b/config/snippet-config/update-workflows.md
@@ -26,11 +26,14 @@ By default, the generated files remain in the source repository's `docs-output/`
 npm run generate:external-snippets -- canton --source-dir ../canton --copy-output --version main
 ```
 
+After copying snippets into `docs-source/`, run `npm run build` and commit both
+`docs-source/` and `docs-main/`.
+
 For repositories with generated snippet JSON, the wrapper runs the required preparation step first. For example, `canton` runs `docs-open / reset` and `docs-open / generateSphinxSnippets` before invoking the extraction helper. Use `--skip-prepare` only when those generated inputs already exist.
 
 # Workflow architecture
 
-Changes in the external repository snippet source files are being extracted on the external repository, wrapped into an artifact and then being pulled in from this repository into the appropriate folder in the `snippets/external/` folder.
+Changes in the external repository snippet source files are being extracted on the external repository, wrapped into an artifact and then being pulled in from this repository into the appropriate folder in the `docs-source/snippets/external/` folder.
 
 
 ## Extract snippet files
@@ -98,7 +101,8 @@ sequenceDiagram
 
   ExtWF->>MainWF: Trigger update_snippets<br/>(artifact-id, run-id, repo-name, repo-org, repo-version)
   MainWF->>Artifact: Download external artifact
-  MainWF->>MainRepo: Copy files to snippets/external/REPO_NAME/REPO_VERSION
+  MainWF->>MainRepo: Copy files to docs-source/snippets/external/REPO_NAME/REPO_VERSION
+  MainWF->>MainRepo: Render/copy docs-source to docs-main
   MainWF->>MainRepo: Detect file changes
   MainWF->>MainRepo: Create/update PR to main<br/>title includes repo/version/short commit hash
 

diff --git a/config/x2mdx/typescript-bindings/source-artifacts.json b/config/x2mdx/typescript-bindings/source-artifacts.json
@@ -7,8 +7,8 @@
       "version_filter": "stable @daml/types npm releases at or above 3.4.8",
       "page_title": "@daml/types",
       "page_description": "TypeScript and JavaScript language bindings for Canton.",
-      "output_file": "docs-main/reference/typescript.mdx",
-      "history_report": "docs-main/reference/typescript/daml-types-history-report.json",
+      "output_file": "docs-source/reference/typescript.mdx",
+      "history_report": "docs-source/reference/typescript/daml-types-history-report.json",
       "surface_id": "typescript-daml-types",
       "entry_point": "index.d.ts",
       "min_version": "3.4.8"
@@ -19,8 +19,8 @@
       "version_filter": "stable @canton-network/wallet-sdk npm releases at or above 1.3.1",
       "page_title": "Wallet SDK",
       "page_description": "TypeScript client library reference for wallet integrations.",
-      "output_file": "docs-main/reference/typescript/wallet-sdk.mdx",
-      "history_report": "docs-main/reference/typescript/wallet-sdk-history-report.json",
+      "output_file": "docs-source/reference/typescript/wallet-sdk.mdx",
+      "history_report": "docs-source/reference/typescript/wallet-sdk-history-report.json",
       "surface_id": "typescript-wallet-sdk",
       "entry_point": "dist/index.d.ts",
       "typedoc_args": [
@@ -34,8 +34,8 @@
       "version_filter": "stable @canton-network/dapp-sdk npm releases at or above 1.1.0",
       "page_title": "dApp SDK",
       "page_description": "TypeScript client library reference for dApp integrations.",
-      "output_file": "docs-main/reference/typescript/dapp-sdk.mdx",
-      "history_report": "docs-main/reference/typescript/dapp-sdk-history-report.json",
+      "output_file": "docs-source/reference/typescript/dapp-sdk.mdx",
+      "history_report": "docs-source/reference/typescript/dapp-sdk-history-report.json",
       "surface_id": "typescript-dapp-sdk",
       "entry_point": "dist/index.d.ts",
       "typedoc_args": [

diff --git a/docs-main/appdev/deep-dives/token-standard.mdx b/docs-main/appdev/deep-dives/token-standard.mdx
@@ -33,7 +33,7 @@ We recommend wallet providers to implement a UTXO management strategy that:
 
 ### Setting up MergeDelegations
 
-{/* NETWORKVARS_START source="/snippets/networkvars/appdev/deep-dives/token-standard-1.mdx" */}
+{/* NETWORKVARS_START source="/appdev/deep-dives/token-standard.mdx" */}
 <Tabs>
 
 <Tab title="DevNet (0.7.5)">

diff --git a/docs-main/edit-source.js b/docs-main/edit-source.js
@@ -0,0 +1,36 @@
+// Mintlify builds Suggest edits from its deployment directory. Keep the branch,
+// filename, query, and fragment, but send contributors to the authored corpus.
+(() => {
+  const selector = 'a[href*="github.com/canton-network/cf-docs/edit/"]';
+
+  function updateLink(link) {
+    const url = new URL(link.href, location.href);
+    if (url.origin !== "https://github.com") return;
+    const sourcePath = url.pathname.replace(
+      /^(\/canton-network\/cf-docs\/edit\/.+\/)docs-main\//,
+      "$1docs-source/",
+    );
+    if (sourcePath === url.pathname) return;
+    url.pathname = sourcePath;
+    link.href = url.href;
+  }
+
+  function updateLinks(root) {
+    if (root.matches?.(selector)) updateLink(root);
+    root.querySelectorAll?.(selector).forEach(updateLink);
+  }
+
+  updateLinks(document);
+  // Consent and client-side navigation can insert or reuse the footer later.
+  new MutationObserver((mutations) => {
+    for (const mutation of mutations) {
+      if (mutation.type === "attributes") updateLinks(mutation.target);
+      else mutation.addedNodes.forEach(updateLinks);
+    }
+  }).observe(document.documentElement, {
+    subtree: true,
+    childList: true,
+    attributes: true,
+    attributeFilter: ["href"],
+  });
+})();
diff --git a/docs-main/global-synchronizer/deployment/kubernetes-deployment.mdx b/docs-main/global-synchronizer/deployment/kubernetes-deployment.mdx
@@ -34,7 +34,7 @@ This section describes deploying a Super Validator (SV) node in kubernetes using
 
 ## Requirements
 
-{/* NETWORKVARS_START source="/snippets/networkvars/global-synchronizer/deployment/kubernetes-deployment-1.mdx" */}
+{/* NETWORKVARS_START source="/global-synchronizer/deployment/kubernetes-deployment.mdx" */}
 <Tabs>
 
 <Tab title="DevNet (0.7.5)">
@@ -351,7 +351,7 @@ Every SV node also deploys a CometBFT node. This node must be configured to join
 
 ### Generating your CometBFT node keys
 
-{/* NETWORKVARS_START source="/snippets/networkvars/global-synchronizer/deployment/kubernetes-deployment-2.mdx" */}
+{/* NETWORKVARS_START source="/global-synchronizer/deployment/kubernetes-deployment.mdx" */}
 <Tabs>
 
 <Tab title="DevNet (0.7.5)">
@@ -505,7 +505,7 @@ All apps support reading the Postgres password from a Kubernetes secret. Current
 
 ### Postgres in the Cluster
 
-{/* NETWORKVARS_START source="/snippets/networkvars/global-synchronizer/deployment/kubernetes-deployment-3.mdx" */}
+{/* NETWORKVARS_START source="/global-synchronizer/deployment/kubernetes-deployment.mdx" */}
 <Tabs>
 
 <Tab title="DevNet (0.7.5)">
@@ -576,7 +576,7 @@ To remove it, set `enableReloader: false` in your Helm values file.
 
 ### Configuring the Helm Charts
 
-{/* NETWORKVARS_START source="/snippets/networkvars/global-synchronizer/deployment/kubernetes-deployment-4.mdx" */}
+{/* NETWORKVARS_START source="/global-synchronizer/deployment/kubernetes-deployment.mdx" */}
 <Tabs>
 
 <Tab title="DevNet (0.7.5)">
@@ -938,7 +938,7 @@ These environment variables will be used below.
 
 ### Installing the Helm Charts
 
-{/* NETWORKVARS_START source="/snippets/networkvars/global-synchronizer/deployment/kubernetes-deployment-5.mdx" */}
+{/* NETWORKVARS_START source="/global-synchronizer/deployment/kubernetes-deployment.mdx" */}
 <Tabs>
 
 <Tab title="DevNet (0.7.5)">
@@ -1202,7 +1202,7 @@ In order to install the reference charts, the following must be satisfied in you
 
 ### Installation Instructions
 
-{/* NETWORKVARS_START source="/snippets/networkvars/global-synchronizer/deployment/kubernetes-deployment-6.mdx" */}
+{/* NETWORKVARS_START source="/global-synchronizer/deployment/kubernetes-deployment.mdx" */}
 <Tabs>
 
 <Tab title="DevNet (0.7.5)">

diff --git a/docs-main/global-synchronizer/deployment/onboarding-process.mdx b/docs-main/global-synchronizer/deployment/onboarding-process.mdx
@@ -33,7 +33,7 @@ Onboarding a Validator involves the following steps (for each network you want t
 
 ## Validating that your IP has been approved
 
-{/* NETWORKVARS_START source="/snippets/networkvars/global-synchronizer/deployment/onboarding-process-1.mdx" */}
+{/* NETWORKVARS_START source="/global-synchronizer/deployment/onboarding-process.mdx" */}
 <Tabs>
 
 <Tab title="DevNet (0.7.5)">

diff --git a/docs-main/global-synchronizer/deployment/required-network-parameters.mdx b/docs-main/global-synchronizer/deployment/required-network-parameters.mdx
@@ -5,7 +5,7 @@ description: "Parameters required to initialise a validator node and connect to
 
 {/* COPIED_START source="splice:docs/src/validator_operator/required_network_parameters.rst" hash="236187bd" */}
 
-{/* NETWORKVARS_START source="/snippets/networkvars/global-synchronizer/deployment/required-network-parameters-1.mdx" */}
+{/* NETWORKVARS_START source="/global-synchronizer/deployment/required-network-parameters.mdx" */}
 <Tabs>
 
 <Tab title="DevNet (0.7.5)">

diff --git a/docs-main/global-synchronizer/deployment/sv-network-resets.mdx b/docs-main/global-synchronizer/deployment/sv-network-resets.mdx
@@ -5,7 +5,7 @@ description: "Handling DevNet and TestNet resets on Super Validator nodes"
 
 {/* COPIED_START source="splice:docs/src/sv_operator/sv_network_resets.rst" hash="1e423aba" */}
 
-{/* NETWORKVARS_START source="/snippets/networkvars/global-synchronizer/deployment/sv-network-resets-1.mdx" */}
+{/* NETWORKVARS_START source="/global-synchronizer/deployment/sv-network-resets.mdx" */}
 <Tabs>
 
 <Tab title="DevNet (0.7.5)">

diff --git a/docs-main/global-synchronizer/deployment/synchronizer-traffic.mdx b/docs-main/global-synchronizer/deployment/synchronizer-traffic.mdx
@@ -36,7 +36,7 @@ Traffic accounting is "by participant"; all parties hosted on the same participa
 
 ## Traffic parameters
 
-{/* NETWORKVARS_START source="/snippets/networkvars/global-synchronizer/deployment/synchronizer-traffic-1.mdx" */}
+{/* NETWORKVARS_START source="/global-synchronizer/deployment/synchronizer-traffic.mdx" */}
 <Tabs>
 
 <Tab title="DevNet (0.7.5)">

diff --git a/docs-main/global-synchronizer/deployment/validator-docker-compose.mdx b/docs-main/global-synchronizer/deployment/validator-docker-compose.mdx
@@ -30,7 +30,7 @@ This deployment is useful for:
 
 ## Requirements
 
-{/* NETWORKVARS_START source="/snippets/networkvars/global-synchronizer/deployment/validator-docker-compose-1.mdx" */}
+{/* NETWORKVARS_START source="/global-synchronizer/deployment/validator-docker-compose.mdx" */}
 <Tabs>
 
 <Tab title="DevNet (0.7.5)">
@@ -244,7 +244,7 @@ Example that proxies external [traffic](/global-synchronizer/deployment/synchron
 
 ## Deployment
 
-{/* NETWORKVARS_START source="/snippets/networkvars/global-synchronizer/deployment/validator-docker-compose-2.mdx" */}
+{/* NETWORKVARS_START source="/global-synchronizer/deployment/validator-docker-compose.mdx" */}
 <Tabs>
 
 <Tab title="DevNet (0.7.5)">