feat: Add a link checker (#2065)

* Initial plan for issue

* Add lychee link checker configuration and CI workflow

Co-authored-by: jcstein <46639943+jcstein@users.noreply.github.com>

* Update link checker config and fix broken internal link

Co-authored-by: jcstein <46639943+jcstein@users.noreply.github.com>

* Potential fix for code scanning alert no. 12: Workflow does not contain permissions

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

* Update link checker config to exclude failing links per review feedback

Co-authored-by: jcstein <46639943+jcstein@users.noreply.github.com>

* docs: remove based64 demo

* Apply suggestions from code review

* Update Polkachu link to point to testnets snapshots page

Co-authored-by: jcstein <46639943+jcstein@users.noreply.github.com>

* Apply suggestions from code review

* Fix missing text at beginning of sentence in data availability FAQ

Co-authored-by: jcstein <46639943+jcstein@users.noreply.github.com>

* Fix CI link checker issues by expanding exclusion patterns

Co-authored-by: jcstein <46639943+jcstein@users.noreply.github.com>

* Fix CI link checker issues and resolve merge conflicts

Co-authored-by: jcstein <46639943+jcstein@users.noreply.github.com>

* Revert excessive exclusions and add only essential link exclusions

Co-authored-by: jcstein <46639943+jcstein@users.noreply.github.com>

* Fix prettier formatting issue in snapshots.md table

Co-authored-by: jcstein <46639943+jcstein@users.noreply.github.com>

* Update link checker configuration and remove Astria links per CI feedback

Co-authored-by: jcstein <46639943+jcstein@users.noreply.github.com>

* Restore Astria menu with Documentation link per request

Co-authored-by: jcstein <46639943+jcstein@users.noreply.github.com>

* Remove broken links from deprecated BlobstreamX documentation

Co-authored-by: jcstein <46639943+jcstein@users.noreply.github.com>

* Apply suggestions from code review

* Apply suggestions from code review

* Apply suggestions from code review

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jcstein <46639943+jcstein@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

Author: 3 people

.github/workflows/link-check.yml

@@ -0,0 +1,29 @@
+name: Link Checker
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    # Run weekly on Monday at 9 AM UTC
+    - cron: '0 9 * * 1'
+
+jobs:
+  link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Link Checker
+        uses: lycheeverse/lychee-action@v2
+        with:
+          # Fail action on broken links
+          fail: true
+          # Use the lychee.toml config file
+          args: --config lychee.toml --verbose '**/*.md' '.vitepress/config.ts'
+          # Optional: set a token for GitHub API access to avoid rate limiting
+          token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -8,6 +8,7 @@ node_modules
 .temp
 .vite_opt_cache
 .vscode
+.lycheecache
 
 # Go build artifacts
 go.sum

.vitepress/config.ts

@@ -6,7 +6,7 @@ const telegramSVG = ` <svg width="24" height="24" viewBox="0 0 24 24" fill="none
 
 const { BASE: base = "/" } = process.env;
 
-// https://vitepress.dev/concepts/site-config
+// VitePress site configuration
 export default {
   lang: "en-US",
   title: "Celestia Docs",
@@ -111,7 +111,7 @@ export default {
   ],
 
   themeConfig: {
-    // https://vitepress.dev/concepts/default-theme-config
+    // VitePress default theme configuration
     nav: nav(),
     outline: {
       level: "deep",
@@ -490,7 +490,7 @@ function sidebarHome() {
                     },
                     {
                       text: "Datastore structure",
-                      link: "how-to-guides/celestia-node-store-structure",
+                      link: "/how-to-guides/celestia-node-store-structure",
                     },
                     {
                       text: "Troubleshooting",
@@ -593,10 +593,6 @@ function sidebarHome() {
                   collapsed: true,
                   items: [
                     { text: "Documentation", link: "https://docs.astria.org" },
-                    {
-                      text: "Just deploy",
-                      link: "https://docs.astria.org/developer/tutorials/install-the-cli",
-                    },
                   ],
                 },
                 {

README.md

@@ -22,6 +22,17 @@ yarn && yarn dev
 
 This documentation site is built with [VitePress](https://vitepress.dev)
 
+## Link checking
+
+To check for broken links in the documentation, run:
+
+```bash
+yarn link-check
+```
+
+This uses [lychee](https://lychee.cli.rs/) to validate all internal and external links.
+The link checker is also run automatically in CI on every push and pull request.
+
 ## Contribution Guidelines
 
 We love contributions from the community! Whether you're fixing typos,

how-to-guides/blobstream-x-requesting-data-commitment-ranges.md

@@ -48,8 +48,7 @@ header range proof.
 ## Request proofs from the Succinct platform
 
 > **_NOTE:_** Requesting a proof from the succinct platform requires
-> having a Succinct API key. It can be requested using
-> this [form](https://alpha.succinct.xyz/partner).
+> having a Succinct API key.
 
 Run the Blobstream X operator with hosted proving on the Succinct
 platform, by running an operator script that pings the platform with
@@ -63,8 +62,7 @@ Here are example values for the `.env` file:
 1. `TENDERMINT_RPC_URL` from
    [the public Celestia list](https://docs.celestia.org/how-to-guides/mainnet#integrations).
 2. `SUCCINCT_RPC_URL` = `https://alpha.succinct.xyz/api`
-3. Request for `SUCCINCT_API_KEY` from
-   [the Succinct team](https://alpha.succinct.xyz/partner).
+3. Request for `SUCCINCT_API_KEY` from the Succinct team.
 4. `CHAIN_ID` is the chain ID of the deployed Blobstream X contract.
 5. `CONTRACT_ADDRESS`: Blobstream X proxy contract address.
 6. `NEXT_HEADER_FUNCTION_ID` & `HEADER_RANGE_FUNCTION_ID`: Get the

how-to-guides/blobstreamx.md

@@ -32,7 +32,7 @@ You can [find the repository for Blobstream X](https://github.com/succinctlabs/b
 along with code for:
 
 - [The Blobstream X smart contract - `BlobstreamX.sol`](https://github.com/succinctlabs/blobstreamx/blob/main/contracts/src/BlobstreamX.sol)
-- [The Blobstream X circuits](https://alpha.succinct.xyz/celestia/blobstreamx)
+- The Blobstream X circuits
 - [The Blobstream X contract Golang bindings](https://github.com/succinctlabs/blobstreamx/blob/main/bindings/BlobstreamX.go)
 
 :::tip NOTE
@@ -57,24 +57,21 @@ X contract is through the `SuccinctGateway` smart contract, which is a
 simple entrypoint contract that verifies proofs (against a deployed
 onchain verifier for the Blobstream X circuit) and then calls the
 `BlobstreamX.sol` contract to update it.
-[Find more information about the `SuccinctGateway`](https://docs.succinct.xyz/platform/onchain-integration#succinct-gateway).
 
 ![blobstream x overview diagram draft](/img/blobstream/Celestia_Blobstream_X2b.png)
 
 <!-- markdownlint-disable MD042 -->
 
 :::tip NOTE
 If the Blobstream X contract is not deployed on a desired chain,
-it needs to be deployed before it can be used by your rollup. See the
-[deployment documentation](https://docs.succinct.xyz/platform/onchain-integration#non-canonical-chain-contract-deployment)
-for more details.
+it needs to be deployed before it can be used by your rollup.
 :::
 
 ## Deploy Blobstream X
 
 It is possible to deploy and maintain a Blobstream x instance and have the same security guarantees.
 
-First, you will need to create a multisig that governs the Blobstream X contract and also the function identifiers. The function identifiers can be registered in the [Succinct gateway](https://docs.succinct.xyz/platform/onchain-integration#register-circuits-with-your-deployed-succinct-gateway).
+First, you will need to create a multisig that governs the Blobstream X contract and also the function identifiers.
 
 Then, check the [deployment](https://github.com/succinctlabs/blobstreamx/blob/main/README.md#blobstreamx-contract-overview) documentation for how to deploy the contract.
 

how-to-guides/celestia-app-multisig.md

@@ -66,7 +66,6 @@ celestia-appd tx multisign unsignedTx.json multisig \
 
 ## Resources
 
-- <https://docs.cosmos.network/main/user/run-node/multisig-guide#step-by-step-guide-to-multisig-transactions>
 - <https://figment.io/insights/how-to-multi-sig-on-cosmos/>
 - <https://github.com/aura-nw/Aura-Safe>
 - <https://github.com/informalsystems/multisig>

how-to-guides/snapshots.md

@@ -49,7 +49,7 @@ Their services include installation scripts, state sync, snapshots, RPC endpoint
 | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
 | Stake Town    | [Pruned](https://services.stake-town.com/home/mainnet/celestia/sync)                                                                           | -                                                                          |
 | ITRocket      | [Pruned](https://itrocket.net/services/mainnet/celestia/) • [Archive](https://itrocket.net/services/mainnet/celestia/)                         | [Archive](https://itrocket.net/services/mainnet/celestia/)                 |
-| Polkachu      | [Pruned](https://polkachu.com/tendermint_snapshots/celestia) • [Archive](https://polkachu.com/archive_snapshots/celestia/)                     | -                                                                          |
+| Polkachu      | [Pruned](https://polkachu.com/tendermint_snapshots/celestia)                                                                                   | -                                                                          |
 | kjnodes       | [Pruned](https://services.kjnodes.com/mainnet/celestia/snapshot/) • [Archive](https://services.kjnodes.com/mainnet/celestia/snapshot-archive/) | -                                                                          |
 | Tienthuattoan | [Pruned](https://services.tienthuattoan.com/mainnet/celestia/snapshot)                                                                         | -                                                                          |
 | Noders        | [Pruned](https://noders.services/mainnet-networks/celestia/snapshot/)                                                                          | -                                                                          |

how-to-guides/sp1-blobstream-deploy.md

@@ -26,7 +26,7 @@ cd sp1-blobstream
    [sp1-blobstream README](https://github.com/succinctlabs/sp1-blobstream?tab=readme-ov-file#deployment).
 
 3. If you're deploying on a chain where there isn't a canonical verifier listed in the
-   [SP1 contract addresses](https://github.com/succinctlabs/sp1/blob/main/book/verification/onchain/contract-addresses.md), you'll need to:
+   [deployed contracts](/how-to-guides/blobstream#deployed-contracts), you'll need to:
 
    a. Deploy your own SP1 Verifier from the [sp1-contracts](https://github.com/succinctlabs/sp1-contracts) matching your `sp1-sdk` version.
    b. Set the `SP1_VERIFIER_ADDRESS` in your `.env` file to the address of your deployed verifier.

learn/how-celestia-works/data-availability-faq.md

@@ -131,8 +131,7 @@ Up until now it’s been all about transaction data, but blockchain state is a
 related topic. The state is different from transaction data. Specifically, the
 state is like a current snapshot of the network, which includes information
 about account balances, smart contract balances, and validator set info.
-[Problems that arise](https://forum.celestia.org/t/the-state-growth-problem-in-a-modular-blockchain-ecosystem/325)
-from the size of the state are different in nature than those around
+Problems that arise from the size of the state are different in nature than those around
 data availability and retrievability.
 
 ## Why doesn’t Celestia incentivize storage of historical data?