celo-org · viral-sangani · Sep 30, 2025 · Sep 30, 2025 · Sep 30, 2025 · Oct 18, 2025
@@ -0,0 +1,46 @@
+name: Documentation Validation
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+    branches:
+      - main
+      - master
+  workflow_dispatch:
+
+jobs:
+  validate-docs:
+    name: Check for Errors and Broken Links
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+
+      - name: Install jq
+        run: sudo apt-get update && sudo apt-get install -y jq
+
+      - name: Install Mintlify CLI
+        run: npm install -g mintlify
+
+      - name: Run validation script
+        id: validate
+        run: |
+          echo "## 📚 Documentation Validation" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Running validation checks using ./scripts/validate-docs.sh" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+
+          # Make script executable and run it
+          chmod +x ./scripts/validate-docs.sh
+          ./scripts/validate-docs.sh
@@ -0,0 +1,54 @@
+name: Mintlify CI Checks
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+    branches:
+      - main
+      - master
+
+jobs:
+  mintlify-checks:
+    name: Run Mintlify CI Checks
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Update system packages
+        run: |
+          sudo apt-get update || echo "apt-get update failed, continuing..."
+
+      - name: Install Mintlify CLI
+        run: npm install -g mintlify
+
+      - name: Run Mintlify validation
+        run: |
+          echo "Running Mintlify validation checks..."
+          mint install || true
+
+          # Note: Mintlify Pro/Enterprise plans have automatic CI checks
+          # This workflow provides additional local validation
+
+          echo "✅ Mintlify validation completed"
+
+      - name: Check deployment readiness
+        run: |
+          echo "Checking if documentation is ready for deployment..."
+
+          # Verify docs.json exists
+          if [ ! -f "docs.json" ]; then
+            echo "❌ Error: docs.json not found"
+            exit 1
+          fi
+
+          echo "✅ Documentation structure is valid"
@@ -1,28 +1,44 @@
-# Mintlify Starter Kit
+# Celo Documentation
 
-Use the starter kit to get your docs deployed and ready to customize.
+Official documentation for Celo, built with [Mintlify](https://mintlify.com).
 
-Click the green **Use this template** button at the top of this repo to copy the Mintlify starter kit. The starter kit contains examples with
+## 🔍 Documentation Validation
 
-- Guide pages
-- Navigation
-- Customizations
-- API reference pages
-- Use of popular components
+We have automated checks for errors and broken links that run on every push and pull request.
 
-**[Follow the full quickstart guide](https://starter.mintlify.com/quickstart)**
+### Quick Validation
+
+Before committing, run local validation:
+
+```bash
+# Run all validation checks
+./scripts/validate-docs.sh
+
+# Check for broken links using Mintlify CLI
+mint broken-links
+```
+
+### CI/CD Workflows
+
+- ✅ **Broken Links Check** - Automatically scans for broken internal/external links
+- ✅ **Structure Validation** - Validates docs.json syntax and structure
+- ✅ **MDX File Verification** - Ensures all referenced files exist
+- ✅ **Syntax Checking** - Detects common MDX/JSX syntax errors
+- ✅ **PR Comments** - Automatically comments on PRs with validation results
+
+Run `./scripts/validate-docs.sh` to check for errors before committing.
 
 ## Development
 
-Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview your documentation changes locally. To install, use the following command:
+Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview your documentation changes locally:
 
 ```sh
 npm i -g mint
 ```
 
 Run the following command at the root of your documentation, where your `docs.json` is located:
 
-```sh
+```bash
 mint dev
 ```
 
@@ -32,14 +48,40 @@ View your local preview at `http://localhost:3000`.
 
 Install our GitHub app from your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app) to propagate changes from your repo to your deployment. Changes are deployed to production automatically after pushing to the default branch.
 
+**Important:** All PRs must pass validation checks before merging.
+
+## Contributing
+
+1. **Before committing:**
+   - Run `./scripts/validate-docs.sh` to check for errors
+   - Test your changes locally with `mint dev`
+   - Ensure all links work correctly
+
+2. **Creating a PR:**
+   - Wait for automated checks to complete
+   - Review any validation warnings or errors
+   - Fix issues before requesting review
+
+3. **For reviewers:**
+   - Check that all validation checks pass
+   - Review any warnings in PR comments
+   - Verify changes render correctly
+
 ## Need help?
 
 ### Troubleshooting
 
-- If your dev environment isn't running: Run `mint update` to ensure you have the most recent version of the CLI.
-- If a page loads as a 404: Make sure you are running in a folder with a valid `docs.json`.
+- **Dev environment not running:** Run `mint update` to ensure you have the most recent version of the CLI
+- **Page loads as 404:** Make sure you are running in a folder with a valid `docs.json`
+- **Validation fails:** Run `./scripts/validate-docs.sh` and review the output for specific errors
+- **Broken links detected:** Review the validation output and fix referenced files or URLs
 
 ### Resources
 
+- [Celo Documentation](https://docs.celo.org)
+- [Validation Script](./scripts/validate-docs.sh)
+- [Mintlify Documentation](https://mintlify.com/docs)
+- [Mintlify Community](https://mintlify.com/community)
+- [Celo Discord](https://discord.com/invite/celo)
 - [Mintlify documentation](https://mintlify.com/docs)
 - [Mintlify community](https://mintlify.com/community)
@@ -77,12 +77,12 @@ There are multiple options.
 
 ### How is the Celo L2 different to Optimism?
 
-See [What's Changed Optimism -> Celo L2](./whats-changed/op-l2).
+See [What's Changed Optimism -> Celo L2](/legacy/transition/optimism/op-l2).
 Also see [Celo L2 Specification](https://specs.celo.org/root.html) for greater detail.
 
 ### What are the costs for L1 data and how are they paid?
 
-See [What's changed section covering L1 fees](/cel2/whats-changed/op-l2#l1-fees).
+See [What's changed section covering L1 fees](/legacy/transition/optimism/op-l2#l1-fees).
 
 ### What's the block time?
 
@@ -94,7 +94,7 @@ The gas limit per block is 30 million, so the maximum throughput is 30M gas/s.
 
 ### Is there anything that used to work on Celo L1 that doesn’t anymore on L2?
 
-See [What's Changed Celo L1 -> L2](/cel2/whats-changed/l1-l2.md) and [L1 -> L2 Migration Changes](https://specs.celo.org/l2_migration.html) in the spec for greater detail.
+See [What's Changed Celo L1 -> L2](/legacy/transition/whats-changed/l1-l2) and [L1 -> L2 Migration Changes](https://specs.celo.org/l2_migration.html) in the spec for greater detail.
 
 ## Testnets
 

@@ -41,7 +41,7 @@ For more specific use-cases for exchanges, please checkout the [Custody and Exch
 
 ### Celo Native Asset and Stable Value Currencies
 
-There are key assets on the Celo network, the Celo native asset (CELO) and Celo-powered Stable Value Currencies, such as Celo Dollar (cUSD) and Celo Euro (cEUR). CELO was formerly called Celo Gold (cGLD) when the contract was deployed, so you will often see references to Celo Gold and CGLD in the codebase. To learn more about the two, please read [this](/developer/migrate/from-ethereum#the-celo-native-asset-and-the-celo-dollar) section of the docs.
+There are key assets on the Celo network, the Celo native asset (CELO) and Celo-powered Stable Value Currencies, such as Celo Dollar (cUSD) and Celo Euro (cEUR). CELO was formerly called Celo Gold (cGLD) when the contract was deployed, so you will often see references to Celo Gold and CGLD in the codebase. To learn more about the two, please read [this](/tooling/overview/migrate/from-ethereum#the-celo-native-asset-and-the-celo-dollar) section of the docs.
 
 You can also view the forum post about the name change [here](https://forum.celo.org/t/proposal-to-rename-celo-gold-to-celo-native-asset/528).
 

@@ -20,8 +20,8 @@ This page describes the historical Celo Layer 1 blockchain. It is useful for und
 
 - Distributed [rewards for validators and validator groups](/what-is-celo/about-celo-l1/protocol/pos/epoch-rewards-validator)
 - Distribute [rewards to holders of Locked CELO](/what-is-celo/about-celo-l1/protocol/pos/epoch-rewards-locked-gold) voting for groups that elected validators
-- Make payments into a [Community Fund](/about-celo/protocol/epoch-rewards/index/community-fund) for protocol infrastructure grants
-- Make payments into a [Carbon Offsetting Fund](/about-celo/protocol/epoch-rewards/index/carbon-offsetting-fund) for carbon offsetting projects
+- Make payments into a [Community Fund](/home/protocol/epoch-rewards/community-fund) for protocol infrastructure grants
+- Make payments into a [Carbon Offsetting Fund](/home/protocol/epoch-rewards/carbon-offsetting-fund) for carbon offsetting projects
 
 A total of 400 million CELO will be released for epoch rewards over time. CELO is a utility and governance asset on Celo, and also the reserve collateral for Celo Dollar (and possibly in the future other whitelisted tokens). It has a fixed total supply and in the long term will exhibit deflationary characteristics similarly to Ethereum.
 

@@ -37,7 +37,7 @@ There are three categories of slashing conditions:
 
 Provable slashing conditions cannot be initiated automatically on chain but information provided from an external source can be definitively verified on-chain.
 
-In exchange for sending a transaction which initiates a successful provable slashing condition on-chain, the reporter receives a "reward", a portion of the slashed amount (which will always be greater than the gas costs of the proof). The reward is added to the reporter's balance of non-voting LockedGold. The remainder of the slashed amount is sent to the [Community Fund](/about-celo/protocol/epoch-rewards/index/community-fund).
+In exchange for sending a transaction which initiates a successful provable slashing condition on-chain, the reporter receives a "reward", a portion of the slashed amount (which will always be greater than the gas costs of the proof). The reward is added to the reporter's balance of non-voting LockedGold. The remainder of the slashed amount is sent to the [Community Fund](/home/protocol/epoch-rewards/community-fund).
 
 - **Persistent downtime -** A validator which can be shown to be absent from 8640 consecutive BLS signatures will be slashed 100 CELO, have future rewards suppressed, and (most importantly in this case) will be ejected from its current group.
 

@@ -31,7 +31,7 @@ If you hold CELO, or are a beneficiary of a [`ReleaseGold` contract](/what-is-ce
 
 CELO that you lock and use to vote for a group that elects one or more Validators receives [epoch rewards](/what-is-celo/about-celo-l1/protocol/pos/epoch-rewards) every epoch (approximately every day) once the community passes a governance proposal enabling rewards. The initial level of rewards is anticipated to be around 6% per annum equivalent (but is subject to change).
 
-Unlike a number of Proof of Stake protocols, **CELO used for voting is never at risk**. The actions of the Validator Groups or Validators you vote for can cause you to receive lower or higher rewards, but the CELO you locked will always be available to be unlocked in the future. [Slashing](/glossary#slashing) in the Celo protocol applies only to Validators and Validator Groups.
+Unlike a number of Proof of Stake protocols, **CELO used for voting is never at risk**. The actions of the Validator Groups or Validators you vote for can cause you to receive lower or higher rewards, but the CELO you locked will always be available to be unlocked in the future. [Slashing](/what-is-celo/about-celo-l1/protocol/pos/penalties) in the Celo protocol applies only to Validators and Validator Groups.
 
 ## Choosing a Validator Group
 

@@ -259,7 +259,7 @@ celocli lockedgold:show $CELO_RG_ADDRESS
 
 ## Vote for a Validator Group
 
-Similar to staking or delegating in other Proof of Stake cryptocurrency protocols, CELO holders can lock CELO and vote for Validator Groups on the Celo network. By doing this, not only do you contribute to the health and security of the network, but you can also earn [epoch rewards](/glossary#epoch-rewards).
+Similar to staking or delegating in other Proof of Stake cryptocurrency protocols, CELO holders can lock CELO and vote for Validator Groups on the Celo network. By doing this, not only do you contribute to the health and security of the network, but you can also earn [epoch rewards](/what-is-celo/about-celo-l1/protocol/pos/epoch-rewards).
 
 For more details, check out the [Voting for Validators page](/what-is-celo/about-celo-l1/validator/voting), which contains useful background on how voting Validator Elections work, as well as more guidance on how to select a Validator Group to vote for. For now, all you need to know is that:
 

@@ -219,7 +219,7 @@ This transaction type is 100% compatible with Ethereum and has no Celo-specific
   [EIP-7702: Set Code for EOAs](https://eips.ethereum.org/EIPS/eip-7702).
 
 - It is scheduled for support on Celo during the
-  [Celo Isthmus](/cel2/notices/isthmus-upgrade.md) hardfork.
+  [Celo Isthmus](/infra-partners/notices/isthmus-upgrade) hardfork.
 
 ### <img width="14" src="/img/doc-images/transaction-types/Celo.jpg" /> Legacy Transaction (`0`)
 

@@ -15,10 +15,10 @@ Explore below how to integrate stablecoins, exchanges, and oracles into your nex
 
 ## Why Stablecoins Matter  
 
-[Stablecoins](build-with-local-stablecoin) are digital assets pegged to a stable reserve, such as fiat currency or a basket of assets. They provide key benefits in DeFi and financial transactions and financial inclusion:  
+[Stablecoins](/build-on-celo/build-with-local-stablecoin) are digital assets pegged to a stable reserve, such as fiat currency or a basket of assets. They provide key benefits in DeFi and financial transactions and financial inclusion:  
 
 <Info>
-Check out ["Build with Stablecoins"](build-with-local-stablecoin) for an extensive list of all stablecoins on Celo.
+Check out ["Build with Stablecoins"](/build-on-celo/build-with-local-stablecoin) for an extensive list of all stablecoins on Celo.
 </Info>
 
 - **Price Stability** – Unlike volatile cryptocurrencies, stablecoins maintain a predictable value.  
@@ -42,7 +42,7 @@ Celo supports a vibrant ecosystem of DeFi protocols that utilize stablecoins:
 
 ### Exchanges
 
-Find all Exchanges [here](/about-celo/exchanges). For cross-chain exchanges check out the [bridges](/developer/bridges) and [cross-chain messaging](/developer/bridges/cross-chain-messaging) pages. 
+Find all Exchanges [here](/home/exchanges). For cross-chain exchanges check out the [bridges](/developer/bridges) and [cross-chain messaging](/developer/bridges/cross-chain-messaging) pages. 
 
 - **[Velodrome](https://velodrome.finance/)** – Velodrome is a decentralized exchange where you can execute low-fee swaps, deposit tokens to earn rewards, and actively participate in the onchain economy.
 - **[Uniswap](https://app.uniswap.org/)** – Swaps and liquidity pools for stablecoins.  

@@ -6,7 +6,7 @@ title: "How it works"
 
 Following Celo's migration to L2, validators have evolved to serve as RPC node providers for the community. The initial active RPC providers were established in Celo L2's genesis block. Subsequently, elections occur at each epoch's conclusion (approximately every 24 hours) to potentially add or remove nodes from the active set.
 
-This system is based on the [proposal for validator engagement during the transition to L2](https://forum.celo.org/t/proposal-validator-engagement-during-the-transition-to-celo-l2/9700) and [Set The Great Celo Halvening Parameters](https://forum.celo.org/t/set-the-great-celo-halvening-parameters/10455/3). For additional details, see [Epoch Rewards](/about-celo/protocol/epoch-rewards/index) and the related [forum discussion: The Great Celo Halvening – Proposed Tokenomics in the Era of Celo L2](https://forum.celo.org/t/the-great-celo-halvening-proposed-tokenomics-in-the-era-of-celo-l2/9701). For updates make sure to refer to the [Celo Forum](https://forum.celo.org).
+This system is based on the [proposal for validator engagement during the transition to L2](https://forum.celo.org/t/proposal-validator-engagement-during-the-transition-to-celo-l2/9700) and [Set The Great Celo Halvening Parameters](https://forum.celo.org/t/set-the-great-celo-halvening-parameters/10455/3). For additional details, see [Epoch Rewards](/home/protocol/epoch-rewards/index) and the related [forum discussion: The Great Celo Halvening – Proposed Tokenomics in the Era of Celo L2](https://forum.celo.org/t/the-great-celo-halvening-proposed-tokenomics-in-the-era-of-celo-l2/9701). For updates make sure to refer to the [Celo Forum](https://forum.celo.org).
 
 <Note>
 ****Terminology****
@@ -26,7 +26,7 @@ The election process follows these steps:
 
 3. **Earn rewards**: Participants receive rewards for their involvement, and validators and groups can also vote and earn rewards using their own stake.
 
-The same Locked CELO can simultaneously be used for multiple purposes: voting in RPC node elections, maintaining Community RPC stakes, and participating in on-chain [Governance](/about-celo/protocol/governance/overview) proposals.
+The same Locked CELO can simultaneously be used for multiple purposes: voting in RPC node elections, maintaining Community RPC stakes, and participating in on-chain [Governance](/home/protocol/governance/overview) proposals.
 
 <Tip>
 **No voter slashing**
@@ -36,7 +36,7 @@ Unlike in other proof-of-stake systems, holding Locked Gold or voting for a grou
 
 ## Implementation
 
-Elections are handled my smart contracts, and as such can be changed through Celo's on-chain [Governance](/about-celo/protocol/governance/overview) process.
+Elections are handled my smart contracts, and as such can be changed through Celo's on-chain [Governance](/home/protocol/governance/overview) process.
 
 - [`Accounts.sol`](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/common/Accounts.sol) manages key delegation and metadata for all accounts including Validators, Groups and Locked Gold holders.
 

@@ -230,7 +230,7 @@ celocli account:register-metadata --url $METADATA_URL --from $CELO_NODE_ADDRESS
 ```
 
 <Note>
-If your account is a [ReleaseGold contract](/about-celo/manage/release-gold), use the command `celocli releasecelo:set-account` instead. Documentation can be found [here](/cli/releasecelo#celocli-releaseceloset-account).
+If your account is a [ReleaseGold contract](/home/manage/release-gold), use the command `celocli releasecelo:set-account` instead. Documentation can be found [here](/cli/releasecelo#celocli-releaseceloset-account).
 </Note>
 
 #### Verify Registration
@@ -326,6 +326,6 @@ celocli lockedcelo:show $CELO_NODE_ADDRESS
 
 ### cUSD Rewards
 
-Active validators receive cUSD rewards based on their validator score, calculated as part of the L2 epoch rewards process (see `EpochRewards.calculateTargetEpochRewards()`). For more details, refer to the [L2 Epoch Rewards documentation](/about-celo/protocol/epoch-rewards/index).
+Active validators receive cUSD rewards based on their validator score, calculated as part of the L2 epoch rewards process (see `EpochRewards.calculateTargetEpochRewards()`). For more details, refer to the [L2 Epoch Rewards documentation](/home/protocol/epoch-rewards/index).
 
 For reward claiming instructions, see [Claiming Rewards](./community-rpc-node#claiming-rewards).