Fix GitHub Pages custom domain baseUrl

When Pages is configured with a custom domain, the site is served from the domain root; build with baseUrl "/" and url set to the custom domain to avoid broken JS/CSS asset paths.

Made-with: Cursor

Author: TheNewAutonomy

.github/workflows/ci.yml

@@ -9,6 +9,9 @@ jobs:
   build:
     runs-on: ubuntu-latest
     timeout-minutes: 15
+    env:
+      # Match production when using a GitHub Pages custom domain.
+      CATALYST_DOCS_CUSTOM_DOMAIN: 'true'
     steps:
       - name: Checkout
         uses: actions/checkout@v4

.github/workflows/pages.yml

@@ -18,6 +18,10 @@ jobs:
   build:
     runs-on: ubuntu-latest
     timeout-minutes: 15
+    env:
+      # When the repo has a GitHub Pages custom domain configured (e.g. docs.catalystnet.org),
+      # the site is served from the domain root and must be built with baseUrl "/".
+      CATALYST_DOCS_CUSTOM_DOMAIN: 'true'
     steps:
       - name: Checkout
         uses: actions/checkout@v4

site/docusaurus.config.ts

@@ -4,6 +4,8 @@ import type * as Preset from '@docusaurus/preset-classic';
 
 // This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
 
+const useCustomDomain = process.env.CATALYST_DOCS_CUSTOM_DOMAIN === 'true';
+
 const config: Config = {
   title: 'Catalyst Docs',
   tagline: 'Operators, wallets, builders, and protocol/RPC reference.',
@@ -14,9 +16,11 @@ const config: Config = {
     v4: true, // Improve compatibility with the upcoming Docusaurus v4
   },
 
-  // GitHub Pages (project pages) URL + baseUrl.
-  url: 'https://catalyst-network.github.io',
-  baseUrl: '/catalyst-docs/',
+  // Hosting:
+  // - GitHub Pages project site: https://catalyst-network.github.io/catalyst-docs/  (baseUrl: /catalyst-docs/)
+  // - Custom domain: https://docs.catalystnet.org/                               (baseUrl: /)
+  url: useCustomDomain ? 'https://docs.catalystnet.org' : 'https://catalyst-network.github.io',
+  baseUrl: useCustomDomain ? '/' : '/catalyst-docs/',
 
   // GitHub pages deployment config.
   organizationName: 'catalyst-network',