Fix AsciiDoc broken references (#6499)

ernestognw · web-flow · commit 8b010f923a0f · 2026-05-07T15:24:01.000-06:00
diff --git a/docs/modules/ROOT/pages/account-abstraction.adoc b/docs/modules/ROOT/pages/account-abstraction.adoc
@@ -79,13 +79,13 @@ To build your own account, see xref:accounts.adoc[accounts].
 
 The smart contract accounts are created by a Factory contract defined by the Account developer. This factory receives arbitrary bytes as `initData` and returns an `address` where the logic of the account is deployed.
 
-To build your own factory, see xref:accounts.adoc#accounts_factory[account factories].
+To build your own factory, see xref:accounts.adoc#accounts-factory[account factories].
 
 === Paymaster Contract
 
 A Paymaster is an optional entity that can sponsor gas fees for Accounts, or allow them to pay for those fees in ERC-20 instead of native currency. This abstracts gas away from the user experience in the same way that computational costs of cloud servers are abstracted away from end-users.
 
-To build your own paymaster, see https://docs.openzeppelin.com/community-contracts/0.0.1/paymasters[paymasters].
+To build your own paymaster, see xref:community-contracts::paymasters.adoc[paymasters].
 
 == Further notes
 
diff --git a/docs/modules/ROOT/pages/accounts.adoc b/docs/modules/ROOT/pages/accounts.adoc
@@ -25,7 +25,7 @@ Since the minimum requirement of xref:api:account.adoc#Account[`Account`] is to
 * xref:api:utils/cryptography.adoc#SignerRSA[`SignerRSA`]: Verifies signatures of traditional PKI systems and X.509 certificates.
 * xref:api:utils/cryptography.adoc#SignerEIP7702[`SignerEIP7702`]: Checks EOA signatures delegated to this signer using https://eips.ethereum.org/EIPS/eip-7702#set-code-transaction[EIP-7702 authorizations]
 * xref:api:utils/cryptography.adoc#SignerERC7913[`SignerERC7913`]: Verifies generalized signatures following https://eips.ethereum.org/EIPS/eip-7913[ERC-7913].
-* https://docs.openzeppelin.com/community-contracts/0.0.1/api/utils/cryptography#SignerZKEmail[`SignerZKEmail`]: Enables email-based authentication for smart contracts using zero-knowledge proofs of email authority signatures.
+* xref:community-contracts::api:utils/cryptography.adoc#SignerZKEmail[`SignerZKEmail`]: Enables email-based authentication for smart contracts using zero-knowledge proofs of email authority signatures.
 * xref:api:utils/cryptography.adoc#MultiSignerERC7913[`MultiSignerERC7913`]: Allows using multiple ERC-7913 signers with a threshold-based signature verification system.
 * xref:api:utils/cryptography.adoc#MultiSignerERC7913Weighted[`MultiSignerERC7913Weighted`]: Overrides the threshold mechanism of xref:api:utils/cryptography.adoc#MultiSignerERC7913[`MultiSignerERC7913`], offering different weights per signer.
 
@@ -46,7 +46,7 @@ Account factories should be carefully implemented to ensure the account address
 
 ==== Handling initialization
 
-Most smart accounts are deployed by a factory, the best practice is to create xref:api:proxy.adoc#minimal_clones[minimal clones] of initializable contracts. These signer implementations provide an initializable design by default so that the factory can interact with the account to set it up right after deployment in a single transaction.
+Most smart accounts are deployed by a factory, the best practice is to create xref:api:proxy.adoc#minimal-clones[minimal clones] of initializable contracts. These signer implementations provide an initializable design by default so that the factory can interact with the account to set it up right after deployment in a single transaction.
 
 [source,solidity]
 ----
@@ -82,7 +82,7 @@ function isValidSignature(bytes32 hash, bytes calldata signature) public view ov
 }
 ----
 
-IMPORTANT: We recommend using xref:api:utils/cryptography.adoc#ERC7739[ERC7739] to avoid replayability across accounts. This defensive rehashing mechanism prevents signatures for this account from being replayed in another account controlled by the same signer. See xref:accounts.adoc#erc_7739_signatures[ERC-7739 signatures].
+IMPORTANT: We recommend using xref:api:utils/cryptography.adoc#ERC7739[ERC7739] to avoid replayability across accounts. This defensive rehashing mechanism prevents signatures for this account from being replayed in another account controlled by the same signer. See xref:accounts.adoc#erc-7739-signatures[ERC-7739 signatures].
 
 === Batched execution
 
@@ -153,7 +153,7 @@ const userOpData = encodeFunctionData({
 
 == Bundle a `UserOperation`
 
-xref:account-abstraction.adoc#useroperation[UserOperations] are a powerful abstraction layer that enable more sophisticated transaction capabilities compared to traditional Ethereum transactions. To get started, you'll need an account, which you can get by xref:accounts.adoc#accounts_factory[deploying a factory] for your implementation.
+xref:account-abstraction.adoc#useroperation[UserOperations] are a powerful abstraction layer that enable more sophisticated transaction capabilities compared to traditional Ethereum transactions. To get started, you'll need an account, which you can get by xref:accounts.adoc#accounts-factory[deploying a factory] for your implementation.
 
 === Preparing a UserOp
 
@@ -335,7 +335,7 @@ A common security practice to prevent user operation https://mirror.xyz/curiousa
 
 The problem with this approach is that the user might be prompted by the wallet provider to sign an https://x.com/howydev/status/1780353754333634738[obfuscated message], which is a phishing vector that may lead to a user losing its assets.
 
-To prevent this, developers may use xref:api:account#ERC7739Signer[`ERC7739Signer`], a utility that implements xref:api:interfaces#IERC1271[`IERC1271`] for smart contract signatures with a defensive rehashing mechanism based on a https://github.com/frangio/eip712-wrapper-for-eip1271[nested EIP-712 approach] to wrap the signature request in a context where there's clearer information for the end user.
+To prevent this, developers may use xref:api:utils/cryptography.adoc#ERC7739[`ERC7739`], a utility that implements xref:api:interfaces.adoc#IERC1271[`IERC1271`] for smart contract signatures with a defensive rehashing mechanism based on a https://github.com/frangio/eip712-wrapper-for-eip1271[nested EIP-712 approach] to wrap the signature request in a context where there's clearer information for the end user.
 
 === EIP-7702 Delegation
 
@@ -351,4 +351,4 @@ Smart accounts have evolved to embrace modularity as a design principle, with po
 
 OpenZeppelin Contracts provides both the building blocks for creating ERC-7579-compliant modules and an xref:api:account.adoc#AccountERC7579[`AccountERC7579`] implementation that supports installing and managing these modules. 
 
-TIP: Learn more in our https://docs.openzeppelin.com/community-contracts/0.0.1/account-modules[account modules] section.
+TIP: Learn more in our xref:community-contracts::account-modules.adoc[account modules] section.
diff --git a/docs/modules/ROOT/pages/eoa-delegation.adoc b/docs/modules/ROOT/pages/eoa-delegation.adoc
@@ -6,7 +6,7 @@ https://eips.ethereum.org/EIPS/eip-7702[EIP-7702] introduces a new transaction t
 * Sponsoring transactions for other users.
 * Implementing privilege de-escalation (e.g., sub-keys with limited permissions)
 
-This section walks you through the process of delegating an EOA to a contract following https://eips.ethereum.org/EIPS/eip-7702[EIP-7702]. This allows you to use your EOA's private key to sign and execute operations with custom execution logic. Combined with https://eips.ethereum.org/EIPS/eip-4337[ERC-4337] infrastructure, users can achieve gas sponsoring through https://docs.openzeppelin.com/community-contracts/paymasters[paymasters].
+This section walks you through the process of delegating an EOA to a contract following https://eips.ethereum.org/EIPS/eip-7702[EIP-7702]. This allows you to use your EOA's private key to sign and execute operations with custom execution logic. Combined with https://eips.ethereum.org/EIPS/eip-4337[ERC-4337] infrastructure, users can achieve gas sponsoring through xref:community-contracts::paymasters.adoc[paymasters].
 
 == Delegating execution
 
@@ -82,7 +82,7 @@ To remove the delegation and restore your EOA to its original state, you can sen
 
 When changing an account's delegation, ensure the newly delegated code is purposely designed and tested as an upgrade to the old one. To ensure safe migration between delegate contracts, use namespaced storage that avoids accidental collisions following ERC-7201. 
 
-WARNING: Updating the delegation designator may render your EOA unusable due to potential storage collisions. We recommend following similar practices to those of https://docs.openzeppelin.com/upgrades-plugins/writing-upgradeable[writing upgradeable smart contracts].
+WARNING: Updating the delegation designator may render your EOA unusable due to potential storage collisions. We recommend following similar practices to those of xref:upgrades-plugins::writing-upgradeable.adoc[writing upgradeable smart contracts].
 
 == Using with ERC-4337
 
@@ -92,7 +92,7 @@ The ability to set code to execute logic on an EOA allows users to leverage ERC-
 
 Once your EOA is delegated to an ERC-4337 compatible account, you can send user operations through the entry point contract. The user operation includes all the necessary fields for execution, including gas limits, fees, and the actual call data to execute. The entry point will validate the operation and execute it in the context of your delegated account.
 
-Similar to how xref:accounts.adoc#bundle_a_useroperation[sending a UserOp] is achieved for factory accounts, here's how you can construct a UserOp for an EOA who's delegated to an xref:api:account.adoc#Account[`Account`] contract.
+Similar to how xref:accounts.adoc#bundle-a-useroperation[sending a UserOp] is achieved for factory accounts, here's how you can construct a UserOp for an EOA who's delegated to an xref:api:account.adoc#Account[`Account`] contract.
 
 [source, typescript]
 ----
diff --git a/docs/modules/ROOT/pages/erc1155.adoc b/docs/modules/ROOT/pages/erc1155.adoc
@@ -1,6 +1,6 @@
 = ERC-1155
 
-ERC-1155 is a novel token standard that aims to take the best from previous standards to create a xref:tokens.adoc#different-kinds-of-tokens[*fungibility-agnostic*] and *gas-efficient* xref:tokens.adoc#but_first_coffee_a_primer_on_token_contracts[token contract].
+ERC-1155 is a novel token standard that aims to take the best from previous standards to create a xref:tokens.adoc#different-kinds-of-tokens[*fungibility-agnostic*] and *gas-efficient* xref:tokens.adoc#but-first-coffee-a-primer-on-token-contracts[token contract].
 
 TIP: ERC-1155 draws ideas from all of xref:erc20.adoc[ERC-20], xref:erc721.adoc[ERC-721], and https://eips.ethereum.org/EIPS/eip-777[ERC-777]. If you're unfamiliar with those standards, head to their guides before moving on.
 
diff --git a/docs/modules/ROOT/pages/erc4626.adoc b/docs/modules/ROOT/pages/erc4626.adoc
@@ -59,10 +59,7 @@ In math that gives:
 
 [%header,cols=4*]
 |===
-|
-| Assets
-| Shares
-| Rate
+|  | Assets | Shares | Rate
 
 | initial
 | stem:[0]
@@ -118,10 +115,7 @@ Following the previous math definitions, we have:
 
 [%header,cols=4*]
 |===
-|
-| Assets
-| Shares
-| Rate
+|  | Assets | Shares | Rate
 
 | initial
 | stem:[1]
diff --git a/docs/modules/ROOT/pages/extending-contracts.adoc b/docs/modules/ROOT/pages/extending-contracts.adoc
@@ -35,7 +35,23 @@ Here is a modified version of xref:api:access.adoc#AccessControl[`AccessControl`
 
 
 ```solidity
-include::api:example$access-control/AccessControlNonRevokableAdmin.sol[]
+// contracts/AccessControlNonRevokableAdmin.sol
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {AccessControl} from "../../../access/AccessControl.sol";
+
+contract AccessControlNonRevokableAdmin is AccessControl {
+    error AccessControlNonRevokable();
+
+    function revokeRole(bytes32 role, address account) public override {
+        if (role == DEFAULT_ADMIN_ROLE) {
+            revert AccessControlNonRevokable();
+        }
+
+        super.revokeRole(role, account);
+    }
+}
 ```
 
 The `super.revokeRole` statement at the end will invoke ``AccessControl``'s original version of `revokeRole`, the same code that would've run if there were no overrides in place.
diff --git a/docs/modules/ROOT/pages/governance.adoc b/docs/modules/ROOT/pages/governance.adoc
@@ -32,7 +32,7 @@ When using a timelock with your Governor contract, you can use either OpenZeppel
 
 https://www.tally.xyz[Tally] is a full-fledged application for user owned on-chain governance. It comprises a voting dashboard, proposal creation wizard, real time research and analysis, and educational content.
 
-For all of these options, the Governor will be compatible with Tally: users will be able to create proposals, see voting periods and delays following xref:api:interfaces.adoc#IERC6372[IERC6372], visualize voting power and advocates, navigate proposals, and cast votes. For proposal creation in particular, projects can also use https://docs.openzeppelin.com/defender/module/actions#transaction-proposals-reference[Defender Transaction Proposals] as an alternative interface.
+For all of these options, the Governor will be compatible with Tally: users will be able to create proposals, see voting periods and delays following xref:api:interfaces.adoc#IERC6372[IERC6372], visualize voting power and advocates, navigate proposals, and cast votes. For proposal creation in particular, projects can also use xref:defender::module/actions.adoc#transaction-proposals-reference[Defender Transaction Proposals] as an alternative interface.
 
 In the rest of this guide, we will focus on a fresh deploy of the vanilla OpenZeppelin Governor features without concern for compatibility with GovernorAlpha or Bravo.
 
@@ -105,7 +105,7 @@ A proposal is a sequence of actions that the Governor contract will perform if i
 
 Let’s say we want to create a proposal to give a team a grant, in the form of ERC-20 tokens from the governance treasury. This proposal will consist of a single action where the target is the ERC-20 token, calldata is the encoded function call `transfer(<team wallet>, <grant amount>)`, and with 0 ETH attached.
 
-Generally a proposal will be created with the help of an interface such as Tally or https://docs.openzeppelin.com/defender/module/actions#transaction-proposals-reference[Defender Proposals]. Here we will show how to create the proposal using Ethers.js.
+Generally a proposal will be created with the help of an interface such as Tally or xref:defender::module/actions.adoc#transaction-proposals-reference[Defender Proposals]. Here we will show how to create the proposal using Ethers.js.
 
 First we get all the parameters necessary for the proposal action.
 
diff --git a/docs/modules/ROOT/pages/multisig.adoc b/docs/modules/ROOT/pages/multisig.adoc
@@ -6,7 +6,7 @@ Popular implementations like https://safe.global/[Safe] (formerly Gnosis Safe) h
 
 == Beyond Standard Signature Verification
 
-As discussed in the xref:accounts.adoc#signature_validation[accounts section], the standard approach for smart contracts to verify signatures is https://eips.ethereum.org/EIPS/eip-1271[ERC-1271], which defines an `isValidSignature(hash, signature)`. However, it is limited in two important ways:
+As discussed in the xref:accounts.adoc#signature-validation[accounts section], the standard approach for smart contracts to verify signatures is https://eips.ethereum.org/EIPS/eip-1271[ERC-1271], which defines an `isValidSignature(hash, signature)`. However, it is limited in two important ways:
 
 1. It assumes the signer has an EVM address
 2. It treats the signer as a single identity
diff --git a/docs/modules/ROOT/pages/tokens.adoc b/docs/modules/ROOT/pages/tokens.adoc
@@ -4,7 +4,7 @@ Ah, the "token": blockchain's most powerful and most misunderstood tool.
 
 A token is a _representation of something in the blockchain_. This something can be money, time, services, shares in a company, a virtual pet, anything. By representing things as tokens, we can allow smart contracts to interact with them, exchange them, create or destroy them.
 
-[[but_first_coffee_a_primer_on_token_contracts]]
+[[but-first-coffee-a-primer-on-token-contracts]]
 == But First, [strikethrough]#Coffee# a Primer on Token Contracts
 
 Much of the confusion surrounding tokens comes from two concepts getting mixed up: _token contracts_ and the actual _tokens_.
diff --git a/docs/modules/ROOT/pages/upgradeable.adoc b/docs/modules/ROOT/pages/upgradeable.adoc
@@ -6,8 +6,6 @@ This variant is available as a separate package called `@openzeppelin/contracts-
 
 It follows all of the rules for xref:upgrades-plugins::writing-upgradeable.adoc[Writing Upgradeable Contracts]: constructors are replaced by initializer functions, state variables are initialized in initializer functions, and we additionally check for storage incompatibilities across minor versions.
 
-TIP: OpenZeppelin provides a full suite of tools for deploying and securing upgradeable smart contracts. xref:openzeppelin::upgrades.adoc[Check out the full list of resources].
-
 == Overview
 
 === Installation
