From c190c06774740eec7137ef048693aa64e98f3fc3 Mon Sep 17 00:00:00 2001 From: winsznx Date: Thu, 11 Dec 2025 13:06:33 +0100 Subject: [PATCH 01/10] docs: Add link checking script, fix numerous broken internal links, and update documentation structure paths. --- .gitbook.yaml | 188 +++++++++++++++++++++++++------------------------- 1 file changed, 94 insertions(+), 94 deletions(-) diff --git a/.gitbook.yaml b/.gitbook.yaml index 9af5f7d276..70c69a7731 100644 --- a/.gitbook.yaml +++ b/.gitbook.yaml @@ -1,97 +1,97 @@ root: ./ redirects: - build-apps/references/bns: clarity/example-contracts/bns.md - build-apps/references/gaia: stacks-in-depth/gaia.md/README.md - docs/blockchain/stacks-blockchain-api: stacks-101/api.md - docs/clarity: clarity/overview.md - docs/clarity/crash-course: clarity/clarity-crash-course.md - docs/clarity/language-functions: clarity/functions.md - docs/clarity/language-keywords: clarity/keywords.md - docs/clarity/language-types: clarity/types.md - docs/clarity/noteworthy-contracts/bns-contract: clarity/example-contracts/bns.md - docs/clarity/noteworthy-contracts/stacking-contract: clarity/example-contracts/stacking.md - docs/clarity/noteworthy-contracts/xbtc: clarity/example-contracts/xbtc.md - docs/clarity/sample-contracts: clarity/example-contracts/audited-starter-contracts.md - docs/clarity/security: clarity/decidability.md - docs/clarity/security/decidable: clarity/decidability.md - docs/contribute: stacks-101/what-is-stacks.md - docs/contribute/docs: stacks-101/what-is-stacks.md - docs/contribute/translations: stacks-101/what-is-stacks.md - docs/cookbook: tutorials/hello-stacks-quickstart-tutorial.md - docs/cookbook/creating-an-ft: tutorials/hello-stacks-quickstart-tutorial.md - docs/cookbook/creating-an-nft: tutorials/hello-stacks-quickstart-tutorial.md - docs/cookbook/get-sats-per-stx: tutorials/hello-stacks-quickstart-tutorial.md - docs/cookbook/parse-a-btc-tx: tutorials/hello-stacks-quickstart-tutorial.md - docs/cookbook/post-conditions: tutorials/hello-stacks-quickstart-tutorial.md - docs/cookbook/sending-bitcoin-with-hiro-wallet: tutorials/hello-stacks-quickstart-tutorial.md - docs/cookbook/stacks-js-auth: tutorials/hello-stacks-quickstart-tutorial.md - docs/cookbook/stacks-js-sending-transactions: tutorials/hello-stacks-quickstart-tutorial.md - docs/cookbook/verifying-a-btc-tx-was-mined: tutorials/hello-stacks-quickstart-tutorial.md - docs/gaia: stacks-in-depth/gaia/README.md - docs/gaia/configuration: stacks-in-depth/gaia/configuration.md - docs/gaia/deploy-gaia-hub: stacks-in-depth/gaia/deploy-gaia-hub.md - docs/gaia/gaia-on-ec2: stacks-in-depth/gaia/gaia-on-ec2.md - docs/gaia/setup-linux: stacks-in-depth/gaia/setup-linux.md - docs/gaia/setup-mac: stacks-in-depth/gaia/setup-mac.md - docs/glossary: stacks-101/what-is-stacks.md - docs/intro: stacks-101/what-is-stacks.md - docs/nakamoto: nakamoto-upgrade/what-is-the-nakamoto-release.md - docs/nakamoto/bitcoin-mev-mitigation: nakamoto-upgrade/nakamoto-in-10-minutes.md - docs/nakamoto/block-production: nakamoto-upgrade/nakamoto-in-10-minutes.md - docs/nakamoto/neon: nakamoto-upgrade/testnets/neon.md - docs/nakamoto/signer: nakamoto-upgrade/running-a-signer.md - docs/nakamoto/stacking: nakamoto-upgrade/stacking-flow.md - docs/next-steps: stacks-101/what-is-stacks.md - docs/nodes-and-miners: stacks-in-depth/nodes-and-miners/README.md - docs/nodes-and-miners/digitalocean: stacks-in-depth/nodes-and-miners/run-a-node-with-digital-ocean.md - docs/nodes-and-miners/hosted-nodes: stacks-in-depth/nodes-and-miners/run-a-node-with-a-hosted-provider.md - docs/nodes-and-miners/miner-costs-and-fees: stacks-in-depth/nodes-and-miners/miner-costs-and-fees.md - docs/nodes-and-miners/miner-mainnet: stacks-in-depth/nodes-and-miners/mine-mainnet-stacks-tokens.md - docs/nodes-and-miners/miner-testnet: stacks-in-depth/nodes-and-miners/mine-testnet-stacks-tokens.md - docs/nodes-and-miners/quicknode: stacks-in-depth/nodes-and-miners/run-a-node-with-quicknode.md - docs/nodes-and-miners/run-a-node: stacks-in-depth/nodes-and-miners/run-a-node-with-docker.md - docs/nodes-and-miners/stacks-node-configuration: stacks-in-depth/nodes-and-miners/stacks-node-configuration.md - docs/nodes-and-miners/verify-miner: stacks-in-depth/nodes-and-miners/verify-miner.md - docs/services-using-stacks/defi: stacks-101/what-is-stacks.md - docs/services-using-stacks/more: stacks-101/what-is-stacks.md - docs/services-using-stacks/nft: stacks-101/what-is-stacks.md - docs/services-using-stacks/stacks-info-sites: stacks-101/what-is-stacks.md - docs/services-using-stacks/wallets: stacks-101/what-is-stacks.md - docs/stacks-academy: stacks-101/what-is-stacks.md - docs/stacks-academy/accounts: stacks-101/accounts.md - docs/stacks-academy/authentication: stacks-101/authentication.md - docs/stacks-academy/bns: stacks-101/bitcoin-name-system.md - docs/stacks-academy/btc-connection: stacks-101/bitcoin-connection.md - docs/stacks-academy/microblocks: nakamoto-upgrade/nakamoto-in-depth/what-about-microblocks.md - docs/stacks-academy/mining: stacks-101/mining.md - docs/stacks-academy/network: stacks-101/network.md - docs/stacks-academy/post-conditions: stacks-101/post-conditions.md - docs/stacks-academy/proof-of-transfer: stacks-101/proof-of-transfer.md - docs/stacks-academy/sips: stacks-101/sips.md - docs/stacks-academy/stacking: stacks-101/stacking.md - docs/stacks-academy/stacks-blockchain-api: stacks-101/api.md - docs/stacks-academy/technical-specs: stacks-101/technical-specifications.md - docs/stacks-academy/testnet: stacks-101/testnet.md - docs/stacks-academy/transactions: stacks-101/transactions.md - docs/stacks-academy/what-is-stacks: stacks-101/what-is-stacks.md - docs/stacks-academy/whitepapers: stacks-101/whitepapers.md - docs/tutorials: tutorials/hello-stacks-quickstart-tutorial.md - docs/tutorials/community-tutorials: tutorials/community-tutorials.md - docs/tutorials/hello-stacks: tutorials/hello-stacks-quickstart-tutorial.md - docs/understand-stacks/testnet: stacks-101/testnet.md - docs/write-smart-contracts: clarity/overview.md - references/bns-contract: clarity/example-contracts/bns.md - references/language-functions: clarity/functions.md - understand-stacks/microblocks: nakamoto-upgrade/nakamoto-in-depth/what-about-microblocks.md - understand-stacks/mining: stacks-101/mining.md - understand-stacks/network: stacks-101/network.md - understand-stacks/proof-of-transfer: stacks-101/proof-of-transfer.md - understand-stacks/stacking: stacks-101/stacking.md - understand-stacks/testnet: stacks-101/testnet.md - understand-stacks/transactions: stacks-101/transactions.md - write-smart-contracts/language-functions: clarity/functions.md - write-smart-contracts/overview: clarity/overview.md - write-smart-contracts/principals: clarity/types.md - write-smart-contracts/tokens: tutorials/tokens.md - sbtc/introduction: concepts/sbtc/README.md + build-apps/references/bns: docs/reference/clarity/example-contracts/bns.md + build-apps/references/gaia: docs/learn/stacks-101/stacks-among-other-layers.md + docs/blockchain/stacks-blockchain-api: docs/learn/stacks-101/README.md + docs/clarity: docs/learn/clarity/overview.md + docs/clarity/crash-course: docs/build/get-started/clarity-crash-course.md + docs/clarity/language-functions: docs/reference/clarity/functions.md + docs/clarity/language-keywords: docs/reference/clarity/keywords.md + docs/clarity/language-types: docs/reference/clarity/types.md + docs/clarity/noteworthy-contracts/bns-contract: docs/reference/clarity/example-contracts/bns.md + docs/clarity/noteworthy-contracts/stacking-contract: docs/reference/clarity/example-contracts/stacking.md + docs/clarity/noteworthy-contracts/xbtc: docs/reference/clarity/example-contracts/xbtc.md + docs/clarity/sample-contracts: docs/reference/clarity/example-contracts/audited-starter-contracts.md + docs/clarity/security: docs/learn/clarity/decidability.md + docs/clarity/security/decidable: docs/learn/clarity/decidability.md + docs/contribute: docs/contribute/README.md + docs/contribute/docs: docs/contribute/README.md + docs/contribute/translations: docs/contribute/README.md + docs/cookbook: docs/build/get-started/developer-quickstart.md + docs/cookbook/creating-an-ft: docs/build/get-started/create-a-token + docs/cookbook/creating-an-nft: docs/build/get-started/create-a-token + docs/cookbook/get-sats-per-stx: docs/build/get-started/developer-quickstart.md + docs/cookbook/parse-a-btc-tx: docs/build/get-started/developer-quickstart.md + docs/cookbook/post-conditions: docs/build/post-conditions/overview.md + docs/cookbook/sending-bitcoin-with-hiro-wallet: docs/build/get-started/developer-quickstart.md + docs/cookbook/stacks-js-auth: docs/build/stacks.js/overview.md + docs/cookbook/stacks-js-sending-transactions: docs/build/stacks.js/build-transactions.md + docs/cookbook/verifying-a-btc-tx-was-mined: docs/build/get-started/developer-quickstart.md + docs/gaia: docs/build/gaia/README.md + docs/gaia/configuration: docs/build/gaia/configuration.md + docs/gaia/deploy-gaia-hub: docs/build/gaia/deploy-gaia-hub.md + docs/gaia/gaia-on-ec2: docs/build/gaia/gaia-on-ec2.md + docs/gaia/setup-linux: docs/build/gaia/setup-linux.md + docs/gaia/setup-mac: docs/build/gaia/setup-mac.md + docs/glossary: docs/learn/stacks-101/what-is-stacks.md + docs/intro: docs/learn/stacks-101/what-is-stacks.md + docs/nakamoto: docs/reference/nakamoto-upgrade/what-is-the-nakamoto-release.md + docs/nakamoto/bitcoin-mev-mitigation: docs/reference/nakamoto-upgrade/nakamoto-in-10-minutes.md + docs/nakamoto/block-production: docs/reference/nakamoto-upgrade/nakamoto-in-10-minutes.md + docs/nakamoto/neon: docs/reference/nakamoto-upgrade/setting-up-a-primary-post-nakamoto-testnet-node.md + docs/nakamoto/signer: docs/operate/run-a-signer/README.md + docs/nakamoto/stacking: docs/operate/stacking-stx/README.md + docs/next-steps: docs/learn/stacks-101/what-is-stacks.md + docs/nodes-and-miners: docs/operate/run-a-node/README.md + docs/nodes-and-miners/digitalocean: docs/operate/run-a-node/run-a-node-with-digital-ocean.md + docs/nodes-and-miners/hosted-nodes: docs/operate/run-a-node/run-a-node-with-a-hosted-provider.md + docs/nodes-and-miners/miner-costs-and-fees: docs/operate/run-a-miner/miner-costs-and-fees.md + docs/nodes-and-miners/miner-mainnet: docs/operate/run-a-miner/mine-mainnet-stacks-tokens.md + docs/nodes-and-miners/miner-testnet: docs/operate/run-a-miner/mine-testnet-stacks-tokens.md + docs/nodes-and-miners/quicknode: docs/operate/run-a-node/run-a-node-with-quicknode.md + docs/nodes-and-miners/run-a-node: docs/operate/run-a-node/run-a-node-with-docker.md + docs/nodes-and-miners/stacks-node-configuration: docs/reference/node-operations/stacks-node-configuration.md + docs/nodes-and-miners/verify-miner: docs/operate/run-a-miner/verify-miner.md + docs/services-using-stacks/defi: docs/learn/stacks-101/what-is-stacks.md + docs/services-using-stacks/more: docs/learn/stacks-101/what-is-stacks.md + docs/services-using-stacks/nft: docs/learn/stacks-101/what-is-stacks.md + docs/services-using-stacks/stacks-info-sites: docs/learn/stacks-101/what-is-stacks.md + docs/services-using-stacks/wallets: docs/learn/stacks-101/what-is-stacks.md + docs/stacks-academy: docs/learn/stacks-101/what-is-stacks.md + docs/stacks-academy/accounts: docs/learn/network-fundamentals/accounts.md + docs/stacks-academy/authentication: docs/learn/network-fundamentals/authentication.md + docs/stacks-academy/bns: docs/learn/network-fundamentals/bitcoin-name-system.md + docs/stacks-academy/btc-connection: docs/learn/stacks-101/bitcoin-connection.md + docs/stacks-academy/microblocks: docs/learn/stacks-101/stacks-among-other-layers.md + docs/stacks-academy/mining: docs/learn/block-production/mining.md + docs/stacks-academy/network: docs/learn/network-fundamentals/network-basics.md + docs/stacks-academy/post-conditions: docs/learn/transactions/post-conditions.md + docs/stacks-academy/proof-of-transfer: docs/learn/stacks-101/proof-of-transfer.md + docs/stacks-academy/sips: docs/learn/network-fundamentals/sips.md + docs/stacks-academy/stacking: docs/learn/block-production/stacking.md + docs/stacks-academy/stacks-blockchain-api: docs/learn/stacks-101/README.md + docs/stacks-academy/technical-specs: docs/learn/network-fundamentals/technical-specifications + docs/stacks-academy/testnet: docs/learn/network-fundamentals/mainnet-and-testnets.md + docs/stacks-academy/transactions: docs/learn/transactions/how-transactions-work.md + docs/stacks-academy/what-is-stacks: docs/learn/stacks-101/what-is-stacks.md + docs/stacks-academy/whitepapers: docs/learn/stacks-101/what-is-stacks.md + docs/tutorials: docs/build/get-started/developer-quickstart.md + docs/tutorials/community-tutorials: docs/build/more-guides/community-tutorials.md + docs/tutorials/hello-stacks: docs/build/get-started/developer-quickstart.md + docs/understand-stacks/testnet: docs/learn/network-fundamentals/mainnet-and-testnets.md + docs/write-smart-contracts: docs/learn/clarity/overview.md + references/bns-contract: docs/reference/clarity/example-contracts/bns.md + references/language-functions: docs/reference/clarity/functions.md + understand-stacks/microblocks: docs/learn/stacks-101/stacks-among-other-layers.md + understand-stacks/mining: docs/learn/block-production/mining.md + understand-stacks/network: docs/learn/network-fundamentals/network-basics.md + understand-stacks/proof-of-transfer: docs/learn/stacks-101/proof-of-transfer.md + understand-stacks/stacking: docs/learn/block-production/stacking.md + understand-stacks/testnet: docs/learn/network-fundamentals/mainnet-and-testnets.md + understand-stacks/transactions: docs/learn/transactions/how-transactions-work.md + write-smart-contracts/language-functions: docs/reference/clarity/functions.md + write-smart-contracts/overview: docs/learn/clarity/overview.md + write-smart-contracts/principals: docs/reference/clarity/types.md + write-smart-contracts/tokens: docs/build/get-started/create-a-token + sbtc/introduction: docs/learn/sbtc/README.md From 2de891074d2413d298c370dc97f4a7dbd9ada87d Mon Sep 17 00:00:00 2001 From: winsznx Date: Thu, 11 Dec 2025 13:08:26 +0100 Subject: [PATCH 02/10] docs: refactor documentation structure, fix internal links, and add a broken link checker script. --- CLAUDE.md | 33 +++---- SUMMARY.md | 255 +++++++++++++++++++---------------------------------- 2 files changed, 108 insertions(+), 180 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 7b917bb174..61bcc705fc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -28,19 +28,20 @@ This repository monitors merged PRs across all Stacks Network and Hiro Systems p ## Documentation Structure ### Primary Documentation Sections -- `/concepts/` - Conceptual documentation about Stacks, PoX, Clarity, sBTC -- `/guides-and-tutorials/` - Hands-on tutorials and how-to guides -- `/reference/` - API reference and technical specifications +- `/docs/learn/` - Conceptual documentation (Stacks 101, sBTC, Block Production) +- `/docs/build/` - Developer guides, tutorials, and tools (Clarinet, Stacks.js) +- `/docs/operate/` - Node operators, miners, and signers guides +- `/docs/reference/` - API reference and technical specifications - `README.md` - Quick start and overview ### Key Documentation Areas -- **Stacks blockchain concepts** - `/concepts/stacks-101/` -- **sBTC documentation** - `/concepts/sbtc/` -- **Clarity language** - `/concepts/clarity/` -- **Node operations** - `/guides-and-tutorials/nodes-and-miners/` -- **Signer operations** - `/guides-and-tutorials/running-a-signer/` -- **Stacking guides** - `/guides-and-tutorials/stack-stx/` -- **Developer quickstart** - `/guides-and-tutorials/hello-stacks-quickstart-tutorial.md` +- **Stacks blockchain concepts** - `/docs/learn/stacks-101/` +- **sBTC documentation** - `/docs/learn/sbtc/` +- **Clarity language** - `/docs/learn/clarity/` +- **Node operations** - `/docs/operate/run-a-node/` +- **Signer operations** - `/docs/operate/run-a-signer/` +- **Stacking guides** - `/docs/operate/stacking-stx/` +- **Developer quickstart** - `/docs/build/get-started/developer-quickstart.md` ## Review Process @@ -58,13 +59,13 @@ This repository monitors merged PRs across all Stacks Network and Hiro Systems p - Does this break existing functionality? 3. **Check documentation** - Search our docs for related content: - - Use `grep -r "relevant_term" concepts/ guides-and-tutorials/ reference/` + - Use `grep -r "relevant_term" docs/learn/ docs/build/ docs/operate/ docs/reference/` - Look for mentions of changed functions, APIs, or concepts - Check if tutorials reference affected code 4. **Be specific** - Point to exact files and sections that need updates - Don't say "update the Clarity docs" - - Say "update `/concepts/clarity/language-functions.md` line 145 to reflect new `map-set` signature" + - Say "update `/docs/reference/clarity/functions.md` line 145 to reflect new `map-set` signature" ### What Requires Documentation @@ -193,13 +194,13 @@ Added a new Clarity built-in function `map-insert` that inserts a key-value pair ## Documentation Impact ### Files Needing Updates -- [ ] `/concepts/clarity/language-functions.md` - Add documentation for map-insert function -- [ ] `/guides-and-tutorials/clarity-hello-world.md` - Update map operations example -- [ ] `/reference/clarity-language-reference.md` - Add to function reference table +- [ ] `/docs/learn/clarity/overview.md` - Add documentation for map-insert function +- [ ] `/docs/build/get-started/clarity-crash-course.md` - Update map operations example +- [ ] `/docs/reference/clarity/functions.md` - Add to function reference table ## Recommended Changes -### In `/concepts/clarity/language-functions.md` +### In `/docs/learn/clarity/overview.md` **Section: Map Functions** diff --git a/SUMMARY.md b/SUMMARY.md index 35bc5744d1..18cf11b92d 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -2,176 +2,103 @@ * [Start Here](README.md) -## ๐Ÿง  Concepts - -* [Stacks 101](concepts/stacks-101/README.md) - * [What Is Stacks?](concepts/stacks-101/what-is-stacks.md) - * [Bitcoin Connection](concepts/stacks-101/bitcoin-connection.md) - * [Proof of Transfer](concepts/stacks-101/proof-of-transfer.md) - * [Stacks Among Other Layers](concepts/stacks-101/stacks-among-other-layers.md) - * [Financial Incentive and Security Budget](concepts/stacks-101/financial-incentive-and-security-budget.md) -* [Network Fundamentals](concepts/network-fundamentals/README.md) - * [Network Basics](concepts/network-fundamentals/network.md) - * [Mainnet and Testnets](concepts/network-fundamentals/mainnet-and-testnets.md) - * [Accounts](concepts/network-fundamentals/accounts.md) - * [Authentication](concepts/network-fundamentals/authentication.md) - * [Bitcoin Name System](concepts/network-fundamentals/bitcoin-name-system.md) - * [SIPs](concepts/network-fundamentals/sips.md) - * [Technical Specifications](concepts/network-fundamentals/technical-specifications/README.md) - * [Audits](concepts/network-fundamentals/technical-specifications/audits.md) -* [Block Production](concepts/block-production/README.md) - * [Mining](concepts/block-production/mining.md) - * [Signing](concepts/block-production/stackers-and-signing.md) - * [Bitcoin Finality](concepts/block-production/bitcoin-finality.md) - * [Bitcoin Reorgs](concepts/block-production/bitcoin-reorgs.md) - * [Stacking](concepts/block-production/stacking.md) -* [Transactions](concepts/transactions/README.md) - * [How Transactions Work](concepts/transactions/transactions.md) - * [Post Conditions](concepts/transactions/post-conditions.md) -* [Clarity](concepts/clarity/README.md) - * [Overview](concepts/clarity/overview.md) - * [Decidability](concepts/clarity/decidability.md) -* [sBTC](concepts/sbtc/README.md) - * [Core Features](concepts/sbtc/core-features.md) - * [sBTC Operations](concepts/sbtc/operations/README.md) - * [Deposit](concepts/sbtc/operations/deposit.md) - * [Withdrawal](concepts/sbtc/operations/withdrawal.md) - * [Deposit vs Withdrawal Times](concepts/sbtc/operations/deposit-withdrawal-times.md) - * [Emily API](concepts/sbtc/emily.md) - * [Peg Wallet UTXO](concepts/sbtc/peg-wallet-utxo.md) - * [Clarity Contracts](concepts/sbtc/clarity-contracts/README.md) - * [sBTC Bootstrap Signers](concepts/sbtc/clarity-contracts/sbtc-bootstrap-signers.md) - * [sBTC Registry](concepts/sbtc/clarity-contracts/sbtc-registry.md) - * [sBTC Token](concepts/sbtc/clarity-contracts/sbtc-token.md) - * [sBTC Deposit](concepts/sbtc/clarity-contracts/sbtc-deposit.md) - * [sBTC Withdrawal](concepts/sbtc/clarity-contracts/sbtc-withdrawal.md) - * [Auxiliary Features](concepts/sbtc/auxiliary-features/README.md) - * [Transaction Fee Sponsorship](concepts/sbtc/auxiliary-features/fee-sponsorship.md) - * [Signer Wallet Rotation](concepts/sbtc/auxiliary-features/signer-wallet-rotation.md) - * [Walkthroughs](concepts/sbtc/walkthroughs/README.md) - * [Signer Process Walkthrough](concepts/sbtc/walkthroughs/signer-process.md) - * [sBTC Transaction Walkthrough](concepts/sbtc/walkthroughs/sbtc-transaction-lifecycle.md) - * [sBTC FAQ](concepts/sbtc/sbtc-faq.md) - * [sBTC Audits](concepts/sbtc/sbtc-audits.md) -* [Gaia](concepts/gaia/README.md) - * [Configuration](concepts/gaia/configuration.md) - * [Deploy Gaia Hub](concepts/gaia/deploy-gaia-hub.md) - * [Amazon EC2](concepts/gaia/amazon-ec2.md) - * [Linux](concepts/gaia/linux.md) - * [Mac OS](concepts/gaia/mac-os.md) - -## ๐Ÿ› ๏ธ Guides & Tutorials - -* [Developer Quickstart](guides-and-tutorials/hello-stacks-quickstart-tutorial.md) -* [Clarity Crash Course](guides-and-tutorials/clarity-crash-course.md) -* [Build a Borrowing & Lending Protocol](guides-and-tutorials/build-a-borrowing-and-lending-protocol.md) -* [Bitcoin Integration](guides-and-tutorials/bitcoin-integration/README.md) - * [Sending Bitcoin with Leather Wallet](guides-and-tutorials/bitcoin-integration/sending-bitcoin-with-leather-wallet.md) - * [Verifying a Bitcoin Transaction](guides-and-tutorials/bitcoin-integration/verifying-a-bitcoin-transaction.md) - * [Parsing a Bitcoin Transaction](guides-and-tutorials/bitcoin-integration/parsing-a-bitcoin-transaction.md) -* [Create Tokens](guides-and-tutorials/tokens/README.md) - * [Creating a NFT](guides-and-tutorials/tokens/creating-a-nft.md) - * [Creating a Fungible Token](guides-and-tutorials/tokens/creating-a-fungible-token.md) -* [Build a Frontend](guides-and-tutorials/frontend/README.md) - * [Post Conditions with Stacks.js](guides-and-tutorials/frontend/post-conditions-with-stacks.js.md) - * [Authentication with Stacks.js](guides-and-tutorials/frontend/authentication-with-stacks.js.md) - * [Sending Transactions with Stacks.js](guides-and-tutorials/frontend/sending-transactions-with-stacks.js.md) -* [Run a Node](guides-and-tutorials/nodes-and-miners/README.md) - * [Run a Node with Docker](guides-and-tutorials/nodes-and-miners/run-a-node-with-docker.md) - * [Run a Node with Digital Ocean](guides-and-tutorials/nodes-and-miners/run-a-node-with-digital-ocean.md) - * [Run a Node with a Hosted Provider](guides-and-tutorials/nodes-and-miners/run-a-node-with-a-hosted-provider.md) - * [Run a Node with Quicknode](guides-and-tutorials/nodes-and-miners/run-a-node-with-quicknode.md) - * [Run a Bitcoin Node](guides-and-tutorials/nodes-and-miners/run-a-bitcoin-node.md) - * [Run a Pruned Bitcoin Node](guides-and-tutorials/nodes-and-miners/run-a-pruned-bitcoin-node.md) -* [Run a Miner](guides-and-tutorials/run-a-miner/README.md) - * [Miner Prerequisites](guides-and-tutorials/run-a-miner/miner-prerequisites.md) - * [Miner Costs and Fees](guides-and-tutorials/run-a-miner/miner-costs-and-fees.md) - * [Mine Testnet Stacks Tokens](guides-and-tutorials/run-a-miner/mine-testnet-stacks-tokens.md) - * [Mine Mainnet Stacks Tokens](guides-and-tutorials/run-a-miner/mine-mainnet-stacks-tokens.md) - * [Verify Miner](guides-and-tutorials/run-a-miner/verify-miner.md) -* [Run a Signer](guides-and-tutorials/running-a-signer/README.md) - * [Signer Quickstart](guides-and-tutorials/running-a-signer/signer-quickstart.md) - * [How to Read Signer Logs](guides-and-tutorials/running-a-signer/how-to-read-signer-logs.md) - * [How to Monitor a Signer](guides-and-tutorials/running-a-signer/how-to-monitor-signer.md) - * [Best practices for running a Signer](guides-and-tutorials/running-a-signer/best-practices-to-run-a-signer.md) - * [OpSec Best Practices](guides-and-tutorials/running-a-signer/opsec-best-practices.md) -* [sBTC](guides-and-tutorials/sbtc/README.md) - * [sBTC Builder Quickstart](guides-and-tutorials/sbtc/sbtc-builder-quickstart.md) - * [How to Run an sBTC Signer](guides-and-tutorials/sbtc/how-to-run-sbtc-signer.md) - * [Best practices for running an sBTC Signer](guides-and-tutorials/sbtc/best-practices-for-running-an-sbtc-signer.md) - * [How to Use the sBTC Bridge](guides-and-tutorials/sbtc/how-to-use-the-sbtc-bridge.md) - * [Earn sBTC Rewards](guides-and-tutorials/sbtc/earn-sbtc-rewards.md) -* [Stack STX](guides-and-tutorials/stack-stx/README.md) - * [Solo Stack](guides-and-tutorials/stack-stx/stacking-flow.md) - * [Operate a Pool](guides-and-tutorials/stack-stx/operate-a-pool.md) - * [Stack with a Pool](guides-and-tutorials/stack-stx/stack-with-a-pool.md) - * [Increase Stacked Position](guides-and-tutorials/stack-stx/increase-stacking.md) - * [Stop Stacking](guides-and-tutorials/stack-stx/stop-stacking.md) -* [Snapshot the chainstate](guides-and-tutorials/best-practices-to-snapshot-the-chainstate.md) -* [Oracles](guides-and-tutorials/oracles.md) -* [Community Tutorials](guides-and-tutorials/community-tutorials.md) +## ๐Ÿง  Learn + +* [Stacks 101](docs/learn/stacks-101/README.md) + * [What Is Stacks?](docs/learn/stacks-101/what-is-stacks.md) + * [Bitcoin Connection](docs/learn/stacks-101/bitcoin-connection.md) + * [Proof of Transfer](docs/learn/stacks-101/proof-of-transfer.md) + * [Stacks Among Other Layers](docs/learn/stacks-101/stacks-among-other-layers.md) + * [Financial Incentive and Security Budget](docs/learn/stacks-101/financial-incentive-and-security-budget.md) +* [Network Fundamentals](docs/learn/network-fundamentals/README.md) + * [Network Basics](docs/learn/network-fundamentals/network-basics.md) + * [Mainnet and Testnets](docs/learn/network-fundamentals/mainnet-and-testnets.md) + * [Accounts](docs/learn/network-fundamentals/accounts.md) + * [Authentication](docs/learn/network-fundamentals/authentication.md) + * [Bitcoin Name System](docs/learn/network-fundamentals/bitcoin-name-system.md) + * [SIPs](docs/learn/network-fundamentals/sips.md) +* [Block Production](docs/learn/block-production/README.md) + * [Mining](docs/learn/block-production/mining.md) + * [Signing](docs/learn/block-production/signing.md) + * [Bitcoin Finality](docs/learn/block-production/bitcoin-finality.md) + * [Bitcoin Reorgs](docs/learn/block-production/bitcoin-reorgs.md) + * [Stacking](docs/learn/block-production/stacking.md) +* [Transactions](docs/learn/transactions/README.md) + * [How Transactions Work](docs/learn/transactions/how-transactions-work.md) + * [Post Conditions](docs/learn/transactions/post-conditions.md) +* [Clarity](docs/learn/clarity/README.md) + * [Overview](docs/learn/clarity/overview.md) + * [Decidability](docs/learn/clarity/decidability.md) +* [sBTC](docs/learn/sbtc/README.md) + * [Core Features](docs/learn/sbtc/core-features.md) + * [Emily API](docs/learn/sbtc/emily-api.md) + * [Peg Wallet UTXO](docs/learn/sbtc/peg-wallet-utxo.md) + * [sBTC FAQ](docs/learn/sbtc/sbtc-faq.md) + +## ๐Ÿ› ๏ธ Build + +* [Get Started](docs/build/get-started/developer-quickstart.md) + * [Developer Quickstart](docs/build/get-started/developer-quickstart.md) + * [Clarity Crash Course](docs/build/get-started/clarity-crash-course.md) +* [Clarinet](docs/build/clarinet/overview.md) + * [Quickstart](docs/build/clarinet/quickstart.md) + * [Project Structure](docs/build/clarinet/project-structure.md) + * [Project Development](docs/build/clarinet/project-development.md) + * [Contract Deployment](docs/build/clarinet/contract-deployment.md) + * [Contract Interaction](docs/build/clarinet/contract-interaction.md) + * [Testing with SDK](docs/build/clarinet/testing-with-clarinet-sdk.md) +* [Stacks.js](docs/build/stacks.js/overview.md) + * [Networks](docs/build/stacks.js/networks.md) + * [Accounts and Addresses](docs/build/stacks.js/accounts-and-addresses.md) + * [Build Transactions](docs/build/stacks.js/build-transactions.md) + * [Contract Calls](docs/build/stacks.js/contract-calls.md) +* [Stacks Connect](docs/build/stacks-connect/connect-wallet.md) + * [Wallet Support](docs/build/stacks-connect/wallet-support.md) + * [Message Signing](docs/build/stacks-connect/message-signing.md) +* [Rendezvous](docs/build/rendezvous/overview.md) + +## ๐Ÿ–ฅ๏ธ Operate + +* [Run a Node](docs/operate/run-a-node/run-a-node-with-docker.md) + * [With Docker](docs/operate/run-a-node/run-a-node-with-docker.md) + * [With Hosted Provider](docs/operate/run-a-node/run-a-node-with-a-hosted-provider.md) + * [With Quicknode](docs/operate/run-a-node/run-a-node-with-quicknode.md) + * [Run a Bitcoin Node](docs/operate/run-a-node/run-a-bitcoin-node.md) +* [Run a Miner](docs/operate/run-a-miner/README.md) + * [Prerequisites](docs/operate/run-a-miner/miner-prerequisites.md) + * [Costs and Fees](docs/operate/run-a-miner/miner-costs-and-fees.md) + * [Mine Testnet](docs/operate/run-a-miner/mine-testnet-stacks-tokens.md) + * [Mine Mainnet](docs/operate/run-a-miner/mine-mainnet-stacks-tokens.md) +* [Run a Signer](docs/operate/run-a-signer/README.md) + * [Quickstart](docs/operate/run-a-signer/signer-quickstart.md) + * [Best Practices](docs/operate/run-a-signer/best-practices-to-run-a-signer.md) + * [Monitoring](docs/operate/run-a-signer/how-to-monitor-signer.md) +* [Stack STX](docs/operate/stacking-stx/README.md) + * [Solo Stack](docs/operate/stacking-stx/solo-stack.md) + * [Stack with Pool](docs/operate/stacking-stx/stack-with-a-pool.md) + * [Operate a Pool](docs/operate/stacking-stx/operate-a-stacking-pool.md) +* [sBTC Signer](docs/operate/run-a-sbtc-signer/README.md) ## ๐Ÿ“š Reference -* [API](reference/api.md) -* [Clarity Types](reference/types.md) -* [Clarity Functions](reference/functions.md) -* [Clarity Keywords](reference/keywords.md) -* [Stacks Node Configuration](reference/stacks-node-configuration.md) -* [Signer Configuration](reference/sample-configuration-files.md) -* [Stacks Tooling](reference/the-stack.md) - -## ๐Ÿ—๏ธ Example Contracts - -* [Audited Starter Contracts](example-contracts/audited-starter-contracts.md) -* [Stacking](example-contracts/stacking.md) -* [BNS](example-contracts/bns.md) -* [Multi Send](example-contracts/multi-send.md) +* [Clarity](docs/reference/clarity/functions.md) + * [Functions](docs/reference/clarity/functions.md) + * [Types](docs/reference/clarity/types.md) + * [Keywords](docs/reference/clarity/keywords.md) +* [Clarinet CLI](docs/reference/clarinet/cli-reference.md) +* [Clarinet JS SDK](docs/reference/clarinet-js-sdk/sdk-reference.md) +* [Stacks Node Config](docs/reference/node-operations/stacks-node-configuration.md) +* [Nakamoto Upgrade](docs/reference/nakamoto-upgrade/nakamoto-upgrade-start-here.md) + * [What is Nakamoto?](docs/reference/nakamoto-upgrade/what-is-the-nakamoto-release.md) + * [In 10 Minutes](docs/reference/nakamoto-upgrade/nakamoto-in-10-minutes.md) + * [Rollout Plan](docs/reference/nakamoto-upgrade/nakamoto-rollout-plan/nakamoto-for-app-developers.md) ## ๐Ÿงก Press & Top Links -* [๐Ÿ”ถ 2024](press-and-top-links/2024/README.md) - * [๐Ÿ”ธ January 2024](press-and-top-links/2024/january-2024.md) - * [๐Ÿ”ธ February 2024](press-and-top-links/2024/february-2024.md) - * [๐Ÿ”ธ March 2024](press-and-top-links/2024/march-2024.md) - * [๐Ÿ”ธ April 2024](press-and-top-links/2024/april-2024.md) - * [๐Ÿ”ธ May 2024](press-and-top-links/2024/may-2024.md) - * [๐Ÿ”ธ June 2024](press-and-top-links/2024/may-2024-1.md) - * [๐Ÿ”ธ July 2024](press-and-top-links/2024/may-2024-2.md) - * [๐Ÿ”ธ August 2024](press-and-top-links/2024/may-2024-3.md) - * [๐Ÿ”ธ September 2024](press-and-top-links/2024/september-2024.md) - * [๐Ÿ”ธ October 2024](press-and-top-links/2024/october-2024.md) - * [๐Ÿ”ธ November 2024](press-and-top-links/2024/october-2024-1.md) - * [๐Ÿ”ธ December 2024](press-and-top-links/2024/october-2024-1-1.md) -* [๐Ÿ”ถ 2025](press-and-top-links/2025/README.md) - * [๐Ÿ”ธ January 2025](press-and-top-links/2025/january-2024.md) - * [๐Ÿ”ธ February 2025](press-and-top-links/2025/february-2025.md) - * [๐Ÿ”ธ March 2025](press-and-top-links/2025/march-2025.md) - * [๐Ÿ”ธ April 2025](press-and-top-links/2025/march-2025-1.md) - * [๐Ÿ”ธ May 2025](press-and-top-links/2025/march-2025-2.md) - * [๐Ÿ”ธ June 2025](press-and-top-links/2025/june-2025.md) - * [๐Ÿ”ธ July 2025](press-and-top-links/2025/june-2025-1.md) - * [๐Ÿ”ธ August 2025](press-and-top-links/2025/june-2025-2.md) - * [๐Ÿ”ธ September 2025](press-and-top-links/2025/june-2025-2-1.md) - -## ๐Ÿงก Bitcoin Theses and Reports - -* [๐ŸŸ  Bitcoin Theses](bitcoin-theses-and-reports/bitcoin-theses.md) -* [๐Ÿ“™ Bitcoin Reports](bitcoin-theses-and-reports/bitcoin-reports.md) +* [2024](docs/press-and-reports/press-and-top-links/2024/README.md) +* [2025](docs/press-and-reports/press-and-top-links/2025/README.md) +* [Bitcoin Reports](docs/press-and-reports/bitcoin-theses-and-reports/bitcoin-reports.md) *** -* [Contribute](contribute.md) - -## ๐ŸŸง Nakamoto Upgrade - -* [Nakamoto Upgrade - Start Here](nakamoto-upgrade/nakamoto-upgrade-start-here.md) -* [What is the Nakamoto Upgrade?](nakamoto-upgrade/what-is-the-nakamoto-release.md) -* [Nakamoto in 10 Minutes](nakamoto-upgrade/nakamoto-in-10-minutes.md) -* [Nakamoto Rollout Plan](nakamoto-upgrade/nakamoto-rollout-plan/README.md) - * [Nakamoto for Stackers](nakamoto-upgrade/nakamoto-rollout-plan/nakamoto-for-stackers.md) - * [Nakamoto for Exchanges](nakamoto-upgrade/nakamoto-rollout-plan/nakamoto-for-exchanges.md) - * [Nakamoto for Stacking Providers](nakamoto-upgrade/nakamoto-rollout-plan/nakamoto-for-stacking-providers.md) - * [Nakamoto for App Developers](nakamoto-upgrade/nakamoto-rollout-plan/nakamoto.md) -* [Setting Up a Primary Nakamoto Testnet Node - Signers](nakamoto-upgrade/setting-up-a-primary-post-nakamoto-testnet-node.md) -* [Nakamoto Activation Guide for Signers](nakamoto-upgrade/nakamoto-activation-guide-for-signers.md) +* [Contribute](docs/contribute/README.md) From 7cde8d18e1854cc6e43669a5c8ef7d56b444778c Mon Sep 17 00:00:00 2001 From: winsznx Date: Thu, 11 Dec 2025 13:08:56 +0100 Subject: [PATCH 03/10] feat: Resolve numerous broken internal documentation links and introduce a link checker script with a report. --- docs/reference/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/README.md b/docs/reference/README.md index daab2b8a5d..b013ee2d44 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -26,7 +26,7 @@ Speaking of [Stacking](https://app.gitbook.com/s/H74xqoobupBWwBsVMJhK/block-prod #### SIP-009 and SIP-010 Tokens -Fungible and non-fungible tokens in Clarity are defined by [SIP-009](file:///) and [SIP-010](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md) standards. You can learn more about how to work with these tokens in the Clarity book. +Fungible and non-fungible tokens in Clarity are defined by [SIP-009](https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md) and [SIP-010](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md) standards. You can learn more about how to work with these tokens in the Clarity book. #### sBTC From 3beb639434eda3868e3364862479c1c44bbfe681 Mon Sep 17 00:00:00 2001 From: winsznx Date: Thu, 11 Dec 2025 13:09:26 +0100 Subject: [PATCH 04/10] fix: Correct broken documentation links and introduce a link checking script. --- docs/build/get-started/clarity-crash-course.md | 2 +- docs/build/get-started/developer-quickstart.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/build/get-started/clarity-crash-course.md b/docs/build/get-started/clarity-crash-course.md index a7eb039f3a..41e989312c 100644 --- a/docs/build/get-started/clarity-crash-course.md +++ b/docs/build/get-started/clarity-crash-course.md @@ -290,7 +290,7 @@ Smart contracts are immutable once deployed. Bugs are permanent. Test them thoro {% endhint %} * [Rendezvous Fuzz Testing](../rendezvous/overview.md): Use Rendezvous to hammer your contract with random inputs. It helps expose edge cases and vulnerabilities. -* [Unit Testing in Clarinet](/broken/pages/xKpkZWiNCO3dwHoA9AeB): Unit testing verifies that individual contract functions behave as expected. +* [Unit Testing in Clarinet](../clarinet/testing-with-clarinet-sdk.md): Unit testing verifies that individual contract functions behave as expected. *** diff --git a/docs/build/get-started/developer-quickstart.md b/docs/build/get-started/developer-quickstart.md index 51092eac5d..c85b6b75c8 100644 --- a/docs/build/get-started/developer-quickstart.md +++ b/docs/build/get-started/developer-quickstart.md @@ -478,7 +478,7 @@ Now with the actual writing of your contract complete, we now need to test its f * Contract interaction in the [Clarinet REPL](../clarinet/contract-interaction.md) * Running your contract in a [local blockchain environment](../clarinet/local-blockchain-development.md) * Fuzz testing with [Rendezvous](https://stacks-network.github.io/rendezvous/) -* Writing unit tests with the [Clarinet JS SDK](/broken/pages/I1W2xGQYVmPwMEEfqje6) +* Writing unit tests with the [Clarinet JS SDK](../../reference/clarinet-js-sdk/sdk-reference.md) We'll go with unit testing for now. In your `tests` folder, open up the related `message-board.test.ts` file and let's use the unit test written below. From 944e6f709ae307a877d97325a3a8a438180addb4 Mon Sep 17 00:00:00 2001 From: winsznx Date: Thu, 11 Dec 2025 13:10:06 +0100 Subject: [PATCH 05/10] feat: Add a broken link checker script and fix identified broken links in documentation. --- docs/build/get-started/build-a-frontend/authentication.md | 2 +- docs/build/get-started/build-a-frontend/post-conditions.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/build/get-started/build-a-frontend/authentication.md b/docs/build/get-started/build-a-frontend/authentication.md index 1d82697bf2..b4f234c9f7 100644 --- a/docs/build/get-started/build-a-frontend/authentication.md +++ b/docs/build/get-started/build-a-frontend/authentication.md @@ -66,4 +66,4 @@ function App() { The `connect()` method comes with the ability to configure how you want the wallet selector modal to appear for your app. You can decide which wallets to have only appear as an option or allow any wallet that follows the SIP-030 standard to appear as an available Stacks wallet. -For the complete guides check out the [Stacks Connect](/broken/pages/JLRpUuDHPMxXaInZ9Vll) section. +For the complete guides check out the [Stacks Connect](../../stacks.js/overview.md) section. diff --git a/docs/build/get-started/build-a-frontend/post-conditions.md b/docs/build/get-started/build-a-frontend/post-conditions.md index ea986b6436..4b1952bf86 100644 --- a/docs/build/get-started/build-a-frontend/post-conditions.md +++ b/docs/build/get-started/build-a-frontend/post-conditions.md @@ -15,7 +15,7 @@ Put simply, post conditions are a set of conditions that must be met before a us They are sent as part of the transaction when the user initiates it, meaning we need to implement post-conditions on the frontend. Whenever you are transferring an asset (fungible or non-fungible) from one address to another, you should take advantage of post conditions. {% hint style="info" %} -Head to the dedicated section on [post-conditions](/broken/pages/0KPrPPKItMGZZL2u4tiF) for more in-depth information. +Head to the dedicated section on [post-conditions](../../../learn/transactions/post-conditions.md) for more in-depth information. {% endhint %} We're going to use [stacks.js](https://github.com/stx-labs/stacks.js/tree/master/packages/transactions#post-conditions) to familiarize ourselves with constructing post-conditions on the frontend. And there are several different ways to construct post-conditions based on asset type. @@ -103,5 +103,5 @@ After transaction confirmation and broadcasting, users are also able to see what ### Additional Resources -* \[[Post-Conditions](/broken/pages/0KPrPPKItMGZZL2u4tiF)] Dedicated section on post-conditions in these docs +* \[[Post-Conditions](../../../learn/transactions/post-conditions.md)] Dedicated section on post-conditions in these docs * \[[Hiro YT](https://youtu.be/xXgQB8NfdEY?si=eSZp4tlLOCkkqGRS)] ELI5: Post-Conditions on Stacks From d0c3c7069c8312db8a832a7f17df067533ba3776 Mon Sep 17 00:00:00 2001 From: winsznx Date: Thu, 11 Dec 2025 13:10:36 +0100 Subject: [PATCH 06/10] feat: introduce broken link checker, fix internal documentation links, and update workflow paths for documentation structure. --- docs/operate/run-a-signer/signer-quickstart.md | 2 +- docs/operate/stacking-stx/operate-a-stacking-pool.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/operate/run-a-signer/signer-quickstart.md b/docs/operate/run-a-signer/signer-quickstart.md index 0617f3f84b..4f5d82cc09 100644 --- a/docs/operate/run-a-signer/signer-quickstart.md +++ b/docs/operate/run-a-signer/signer-quickstart.md @@ -18,7 +18,7 @@ If you want to get up and running as an active signer as quickly as possible, he If you are not familiar with how signing works yet, be sure to check out the [Signing concept guide](https://app.gitbook.com/s/H74xqoobupBWwBsVMJhK/block-production/signing). -If you would like a more detailed walkthrough of all of these steps, take a look at the [Running a Signer](file:///) guide. +If you would like a more detailed walkthrough of all of these steps, take a look at the [Running a Signer](README.md) guide. {% hint style="danger" %} The CLI examples below may show outdated release versions. For the latest releases, always refer to the links above in the top info block. diff --git a/docs/operate/stacking-stx/operate-a-stacking-pool.md b/docs/operate/stacking-stx/operate-a-stacking-pool.md index af5832a237..baf2f21dd0 100644 --- a/docs/operate/stacking-stx/operate-a-stacking-pool.md +++ b/docs/operate/stacking-stx/operate-a-stacking-pool.md @@ -586,4 +586,4 @@ Once a pool has enough delegated STX to become a signer, the pool admin needs to Once this transaction has been confirmed, the pool operator is eligible to be a signer for an upcoming reward cycle. -For more on the relationship between automated signing and manual stacking transactions, be sure to check out the main [Stack STX](file:///) doc. +For more on the relationship between automated signing and manual stacking transactions, be sure to check out the main [Stack STX](README.md) doc. From 26946637ad9ef37b52aacfe91b70b116eb2533da Mon Sep 17 00:00:00 2001 From: winsznx Date: Thu, 11 Dec 2025 13:10:53 +0100 Subject: [PATCH 07/10] feat: Implement a broken link checker script, generate a report, fix an internal link, and update documentation structure references. --- broken_links_report.csv | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 broken_links_report.csv diff --git a/broken_links_report.csv b/broken_links_report.csv new file mode 100644 index 0000000000..31bbae1861 --- /dev/null +++ b/broken_links_report.csv @@ -0,0 +1,26 @@ +File,Line,Link Text,Target,Resolved Path +docs/press-and-reports/press-and-top-links/2024/README.md,12,Broken link,/broken/pages/cd2e8707fe40b8a43e40923a688434e9aaf4922e,/broken/pages/cd2e8707fe40b8a43e40923a688434e9aaf4922e +docs/press-and-reports/press-and-top-links/2024/README.md,16,Broken link,/broken/pages/29b9f8cda45db86fe5031ee567341583324e2f6b,/broken/pages/29b9f8cda45db86fe5031ee567341583324e2f6b +docs/press-and-reports/press-and-top-links/2024/README.md,20,Broken link,/broken/pages/e7761aa2c81d3c8245dbc54570199f1aebd91325,/broken/pages/e7761aa2c81d3c8245dbc54570199f1aebd91325 +docs/press-and-reports/press-and-top-links/2024/README.md,24,Broken link,/broken/pages/bbb9712e169fccb44833d8d9f0d98ad2bccd62f2,/broken/pages/bbb9712e169fccb44833d8d9f0d98ad2bccd62f2 +docs/press-and-reports/press-and-top-links/2024/README.md,28,Broken link,/broken/pages/aec6e9d8a50d144e48a1dfdc8af0e834cd9af457,/broken/pages/aec6e9d8a50d144e48a1dfdc8af0e834cd9af457 +docs/press-and-reports/press-and-top-links/2024/README.md,32,Broken link,/broken/pages/629cc20de749db943380bddf1d69842a2863033c,/broken/pages/629cc20de749db943380bddf1d69842a2863033c +docs/press-and-reports/press-and-top-links/2024/README.md,36,Broken link,/broken/pages/cf07211cab8be8b227dee91931874e3fe5792b8d,/broken/pages/cf07211cab8be8b227dee91931874e3fe5792b8d +docs/press-and-reports/press-and-top-links/2024/README.md,40,Broken link,/broken/pages/1fc9a3503ea5c373fb758dc9be7401b5f70501d4,/broken/pages/1fc9a3503ea5c373fb758dc9be7401b5f70501d4 +docs/press-and-reports/press-and-top-links/2024/README.md,44,Broken link,/broken/pages/db2a454141ac04ca7ea4bc2666e5af5fab4deb68,/broken/pages/db2a454141ac04ca7ea4bc2666e5af5fab4deb68 +docs/press-and-reports/press-and-top-links/2024/README.md,48,Broken link,/broken/pages/4050fecb50c952b844915fafb1b214eb349e1931,/broken/pages/4050fecb50c952b844915fafb1b214eb349e1931 +docs/press-and-reports/press-and-top-links/2024/README.md,52,Broken link,/broken/pages/68a55e4003881342d50a527d6f8e683cd5803dde,/broken/pages/68a55e4003881342d50a527d6f8e683cd5803dde +docs/press-and-reports/press-and-top-links/2024/README.md,56,Broken link,/broken/pages/bd6ef1fe15c0f8e10163ba8857053effe9eb20da,/broken/pages/bd6ef1fe15c0f8e10163ba8857053effe9eb20da +docs/operate/run-a-signer/README.md,339,Stack STX,broken-reference,/Users/macbook/docs/docs/operate/run-a-signer/broken-reference +docs/operate/stacking-stx/solo-stack.md,471,generate your signer key,broken-reference,/Users/macbook/docs/docs/operate/stacking-stx/broken-reference +docs/build/README.md,45,Learn Clarinet,/broken/pages/UK5Kgh2MHLoQvfoFVnLr,/broken/pages/UK5Kgh2MHLoQvfoFVnLr +docs/build/get-started/build-a-frontend/sending-transactions.md,88,[Learn Stacks.js,/broken/pages/dH5waQhE6Vb7rhcrUG7z,/broken/pages/dH5waQhE6Vb7rhcrUG7z +docs/reference/node-operations/stacks-node-configuration.md,4,Signer Configuration,/broken/pages/8ea1fa91cfa819c25f545b0aca9bfc16c8c3ad28,/broken/pages/8ea1fa91cfa819c25f545b0aca9bfc16c8c3ad28 +docs/reference/node-operations/signer-configuration.md,27,How to Run a Signer,/broken/pages/261edd335c0b98fb052ad55906fbf90832800453,/broken/pages/261edd335c0b98fb052ad55906fbf90832800453 +docs/reference/node-operations/signer-configuration.md,66,How to Run a Signer,/broken/pages/261edd335c0b98fb052ad55906fbf90832800453,/broken/pages/261edd335c0b98fb052ad55906fbf90832800453 +docs/reference/node-operations/signer-configuration.md,68,Stacks Node Configuration,/broken/pages/79a6d21c88b879210b9f2036268ace38ae6a02af,/broken/pages/79a6d21c88b879210b9f2036268ace38ae6a02af +docs/reference/nakamoto-upgrade/nakamoto-rollout-plan/nakamoto-for-exchanges.md,9,Broken link,/broken/pages/fac008cad2409afc8de86501f205ee51e148b5af "mention",/broken/pages/fac008cad2409afc8de86501f205ee51e148b5af "mention" +docs/reference/clarity/example-contracts/stacking.md,19,familiarize yourself with that first,/broken/pages/3df1d5b76fd4f047544069a38895455776fc228f,/broken/pages/3df1d5b76fd4f047544069a38895455776fc228f +docs/reference/clarity/example-contracts/stacking.md,95,How to Stack,/broken/pages/930b16324611cdbf3451ca2b306ada93a1be367e,/broken/pages/930b16324611cdbf3451ca2b306ada93a1be367e +docs/reference/clarity/example-contracts/stacking.md,96,How to Run a Signer,/broken/pages/5baf2f4c67696dbef7258f50d4cbf103b3e014d1,/broken/pages/5baf2f4c67696dbef7258f50d4cbf103b3e014d1 +docs/reference/clarity/example-contracts/stacking.md,416,stacking guide,/broken/pages/930b16324611cdbf3451ca2b306ada93a1be367e#delegator-initiates-delegation,/broken/pages/930b16324611cdbf3451ca2b306ada93a1be367e From 8b8e44a25253f23b00cb48ed8066ecef7982024f Mon Sep 17 00:00:00 2001 From: winsznx Date: Thu, 11 Dec 2025 13:11:18 +0100 Subject: [PATCH 08/10] chore: Introduce a markdown link checker, update documentation workflow paths, and fix a broken internal link. --- check_links.py | 81 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 check_links.py diff --git a/check_links.py b/check_links.py new file mode 100644 index 0000000000..3127124b95 --- /dev/null +++ b/check_links.py @@ -0,0 +1,81 @@ +import os +import re +from pathlib import Path +import urllib.parse + +def check_links(root_dir): + # Match [text](link) or [text]: link + link_pattern = re.compile(r'\[([^\]]+)\]\(([^)]+)\)') + + root_path = Path(root_dir).resolve() + broken_links = [] + + print(f"Scanning for broken links in {root_path}...") + + for markdown_file in root_path.rglob('*.md'): + # Skip node_modules or .git + if '.git' in markdown_file.parts or 'node_modules' in markdown_file.parts: + continue + + try: + content = markdown_file.read_text() + except Exception as e: + print(f"Could not read {markdown_file}: {e}") + continue + + # Find all lines with links + lines = content.split('\n') + for line_num, line in enumerate(lines, 1): + matches = link_pattern.findall(line) + for text, link in matches: + # Ignore external links, anchors, and mailto + if link.startswith(('http', 'https', 'mailto:', '#', '<')): + continue + + # split anchor if present + url_parts = link.split('#') + file_part = url_parts[0] + + if not file_part: + # just an anchor on same page + continue + + # Resolve relative path + try: + # Decode URL encoding (e.g. %20 -> space) + file_part = urllib.parse.unquote(file_part) + + target_path = (markdown_file.parent / file_part).resolve() + + if not target_path.exists(): + # Check if it might be a directory with README.md implicit + if not target_path.exists() and not file_part.endswith('.md'): + target_path_md = (markdown_file.parent / (file_part + ".md")).resolve() + if target_path_md.exists(): + continue + + relative_path = markdown_file.relative_to(root_path) + broken_links.append({ + 'file': str(relative_path), + 'line': line_num, + 'text': text, + 'target': link, + 'resolved': str(target_path) + }) + except Exception as e: + print(f"Error checking link {link} in {markdown_file}: {e}") + + return broken_links + +if __name__ == "__main__": + broken = check_links(".") + + if broken: + print(f"\nFound {len(broken)} broken links:") + with open('broken_links_report.csv', 'w') as f: + f.write("File,Line,Link Text,Target,Resolved Path\n") + for link in broken: + print(f"{link['file']}:{link['line']} -> {link['target']}") + f.write(f"{link['file']},{link['line']},{link['text']},{link['target']},{link['resolved']}\n") + else: + print("\nNo broken links found!") From 944cf98a60943cb8d306e3a9298a56dc4954e26e Mon Sep 17 00:00:00 2001 From: winsznx Date: Thu, 11 Dec 2025 13:11:34 +0100 Subject: [PATCH 09/10] docs: Update documentation directory paths in workflow and fix broken link in mining guide. --- .github/workflows/smart-docs-monitor.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/smart-docs-monitor.yml b/.github/workflows/smart-docs-monitor.yml index 5cadc49afd..5dc5128da8 100644 --- a/.github/workflows/smart-docs-monitor.yml +++ b/.github/workflows/smart-docs-monitor.yml @@ -103,9 +103,9 @@ jobs: - Determine if it affects user-facing features, APIs, or workflows 3. **Review our documentation:** - - Check /concepts directory for all conceptual documentation - - Check /guides-and-tutorials directory for tutorials and how-to guides - - Check /reference directory for API and reference documentation + - Check /docs/learn directory for all conceptual documentation + - Check /docs/build and /docs/operate directories for tutorials and guides + - Check /docs/reference directory for API and reference documentation - Read README.md - Look for setup/configuration guides From 9c79fa0a28d6ed80bb1d7da97857762d68274a89 Mon Sep 17 00:00:00 2001 From: winsznx Date: Thu, 11 Dec 2025 13:11:46 +0100 Subject: [PATCH 10/10] docs: Fix broken internal link to block production process. --- docs/learn/block-production/mining.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/learn/block-production/mining.md b/docs/learn/block-production/mining.md index 60b6677f0f..8709ebccab 100644 --- a/docs/learn/block-production/mining.md +++ b/docs/learn/block-production/mining.md @@ -87,7 +87,7 @@ Stacks miners function similarly to sequencers in L2 systems in that they are on It's important to note that there are two primary parties involved in the block production process on Stacks: miners and stackers. -These two roles serve complementary relationships in the [block production process](file:///), and stackers drastically reduce any potential destructive power miners have over the chain. +These two roles serve complementary relationships in the [block production process](README.md), and stackers drastically reduce any potential destructive power miners have over the chain. Miners cannot reorganize the chain. In the worst case, all miners can do is omit (some kinds of) transactions, and all that is required to address this is to run your own miner.