Capture special cases in convert-adoc.js

Author: ernestognw

content/community-contracts/crosschain.mdx

@@ -95,7 +95,7 @@ function sendMessage(
     // Post on all gateways
     Outbox[] memory outbox = new Outbox[](_gateways.length());
     bool needsId = false;
-    for (uint256 i = 0; i < outbox.length; `i) {
+    for (uint256 i = 0; i < outbox.length; ++i) {
         address gateway = _gateways.at(i);
         // send message
         bytes32 id = IERC7786GatewaySource(gateway).sendMessage(
@@ -132,7 +132,7 @@ function receiveMessage(
     if (_gateways.contains(msg.sender) && !tracker.receivedBy[msg.sender]) {
         // Count number of time received
         tracker.receivedBy[msg.sender] = true;
-        `tracker.countReceived;
+        ++tracker.countReceived;
         emit Received(id, msg.sender);
 
     // if already executed, leave gracefully
@@ -162,4 +162,4 @@ function receiveMessage(
 }
 ```
 
-The bridge is designed to be configurable. As an `Ownable` contract, it allows the owner to manage the list of trusted gateways and adjust the confirmation threshold. The `_gateways` list and threshold are initially set during contract deployment using the [`+_addGateway+`](/community-contracts/api/crosschain#ERC7786OpenBridge-_addGateway-address-) and [`+_setThreshold+`](/community-contracts/api/crosschain#ERC7786OpenBridge-_setThreshold-uint8-) functions. The owner can update these settings as needed to adapt to changing requirements or add new gateways.
+The bridge is designed to be configurable. As an `Ownable` contract, it allows the owner to manage the list of trusted gateways and adjust the confirmation threshold. The `_gateways` list and threshold are initially set during contract deployment using the [`_addGateway`](/community-contracts/api/crosschain#ERC7786OpenBridge-_addGateway-address-) and [`_setThreshold`](/community-contracts/api/crosschain#ERC7786OpenBridge-_setThreshold-uint8-) functions. The owner can update these settings as needed to adapt to changing requirements or add new gateways.

content/community-contracts/index.mdx

@@ -42,4 +42,4 @@ Contracts in the community library are provided as is, with no particular guaran
 
 Similarly, the code has no backward compatibility guarantees.
 
-We kindly ask to report any issue directly to our security mailto:security@openzeppelin.org[contact]. The team will do its best to assist and mitigate any potential misuses of the library. However, keep in mind the flexibility assumed for this repository may relax our assessment.
+We kindly ask to report any issue directly to our security [contact](mailto:security@openzeppelin.org). The team will do its best to assist and mitigate any potential misuses of the library. However, keep in mind the flexibility assumed for this repository may relax our assessment.

content/confidential-contracts/index.mdx

@@ -14,4 +14,4 @@ Contracts in the confidential contracts library are provided as is, with no part
 
 Similarly, the code has no backward compatibility guarantees.
 
-We kindly ask to report any issue directly to our security mailto:security@openzeppelin.org[contact]. The team will do its best to assist and mitigate any potential misuses of the library. However, keep in mind the flexibility assumed for this repository may relax our assessment.
+We kindly ask to report any issue directly to our security [contact](mailto:security@openzeppelin.org). The team will do its best to assist and mitigate any potential misuses of the library. However, keep in mind the flexibility assumed for this repository may relax our assessment.

content/confidential-contracts/token.mdx

@@ -41,7 +41,7 @@ Setting an operator for any amount of time allows the operator to _***take all o
 
 The token standard exposes transfer functions with and without callbacks. It is up to the caller to decide if a callback is necessary for the transfer. For smart contracts that support it, callbacks allow the operator approval step to be skipped and directly invoke the receiver contract via a callback.
 
-Smart contracts that are the target of a callback must implement [`+IERC7984Receiver+`](/confidential-contracts/api/interfaces#IERC7984Receiver). After balances are updated for a transfer, the callback is triggered by calling the [`+onConfidentialTransferReceived+`](/confidential-contracts/api/interfaces#IERC7984Receiver-onConfidentialTransferReceived-address-address-euint64-bytes-) function. The function must either revert or return an `ebool` indicating success. If the callback returns false, the token transfer is reversed.
+Smart contracts that are the target of a callback must implement [`IERC7984Receiver`](/confidential-contracts/api/interfaces#IERC7984Receiver). After balances are updated for a transfer, the callback is triggered by calling the [`onConfidentialTransferReceived`](/confidential-contracts/api/interfaces#IERC7984Receiver-onConfidentialTransferReceived-address-address-euint64-bytes-) function. The function must either revert or return an `ebool` indicating success. If the callback returns false, the token transfer is reversed.
 
 ## Examples
 

content/contracts/5.x/access-control.mdx

@@ -96,7 +96,7 @@ These can be used to iterate over the accounts that have been granted a role:
 const minterCount = await myToken.getRoleMemberCount(MINTER_ROLE);
 
 const members = [];
-for (let i = 0; i < minterCount; i) {
+for (let i = 0; i < minterCount; ++i) {
     members.push(await myToken.getRoleMember(MINTER_ROLE, i));
 }
 ```
@@ -282,7 +282,7 @@ This adds function that can be queried to iterate over the accounts that have be
 const minterCount = await accessManager.getRoleMemberCount(MINTER_ROLE);
 
 const members = [];
-for (let i = 0; i < minterCount; `i) {
+for (let i = 0; i < minterCount; ++i) {
     members.push(await accessManager.getRoleMember(MINTER_ROLE, i));
 }
 
@@ -292,7 +292,7 @@ const target = await myToken.getAddress();
 const functionCount = await accessManager.getRoleTargetFunctionCount(MINTER_ROLE, target);
 
 const functions = [];
-for (let i = 0; i < functionCount; `i) {
+for (let i = 0; i < functionCount; ++i) {
     functions.push(await accessManager.getRoleTargetFunction(MINTER_ROLE, target, i));
 }
 

content/contracts/5.x/erc1155.mdx

@@ -71,9 +71,9 @@ The metadata uri can be obtained:
 "https://game.example/api/item/{id}.json"
 ```
 
-The `uri` can include the string `+id+` which clients must replace with the actual token ID, in lowercase hexadecimal (with no 0x prefix) and leading zero padded to 64 hex characters.
+The `uri` can include the string `id` which clients must replace with the actual token ID, in lowercase hexadecimal (with no 0x prefix) and leading zero padded to 64 hex characters.
 
-For token ID `2` and uri `+https://game.example/api/item/id.json+` clients would replace `+id+` with `0000000000000000000000000000000000000000000000000000000000000002` to retrieve JSON at `https://game.example/api/item/0000000000000000000000000000000000000000000000000000000000000002.json`.
+For token ID `2` and uri `https://game.example/api/item/id.json` clients would replace `id` with `0000000000000000000000000000000000000000000000000000000000000002` to retrieve JSON at `https://game.example/api/item/0000000000000000000000000000000000000000000000000000000000000002.json`.
 
 The JSON document for token ID 2 might look something like:
 

content/contracts/5.x/utilities.mdx

@@ -493,7 +493,7 @@ The [`Memory`](/contracts/5.x/api/utils#Memory) library provides functions for a
 
 ```solidity
 function processMultipleItems(uint256[] memory items) internal {
-  for (uint256 i = 0; i < items.length; i`) {
+  for (uint256 i = 0; i < items.length; i++) {
     bytes memory tempData = abi.encode(items[i], block.timestamp);
     // Process tempData...
   }
@@ -505,7 +505,7 @@ Note that each iteration allocates new memory for `tempData`, causing the memory
 ```solidity
 function processMultipleItems(uint256[] memory items) internal {
   Memory.Pointer ptr = Memory.getFreeMemoryPointer(); // Cache pointer
-  for (uint256 i = 0; i < items.length; i`) {
+  for (uint256 i = 0; i < items.length; i++) {
     bytes memory tempData = abi.encode(items[i], block.timestamp);
     // Process tempData...
     Memory.unsafeSetFreeMemoryPointer(ptr); // Reset pointer for reuse

scripts/convert-adoc.js

@@ -188,22 +188,36 @@ async function convertAdocFiles(directory, apiRoute = "contracts/5.x/api") {
 			mdContent = mdContent.replace(/<dl>/g, "");
 			mdContent = mdContent.replace(/<\/dl>/g, "");
 
-			// Fix AsciiDoc monospace formatting (++ to backticks)
-			// Handle ++text++ -> `text`
-			mdContent = mdContent.replace(/\+\+([^+]+)\+\+/g, "`$1`");
-
-			// Fix any remaining ++ that might be standalone
-			mdContent = mdContent.replace(/\+\+/g, "");
-
-			// Escape bare < that aren't HTML/JSX tag starts (e.g., "<1 share",
-			// "< 0x80") to prevent MDX parse errors. Skip code blocks and
-			// inline code — content there is rendered verbatim, so escaping
-			// would corrupt it (e.g. `<4.6 to >=4.6`).
-			const ltSplit = mdContent.split(/(```[\s\S]*?```|`[^`\n]*`)/g);
-			mdContent = ltSplit
-				.map((part, idx) =>
-					idx % 2 === 1 ? part : part.replace(/(<)(\s+\w|\d)/g, "&lt;$2"),
-				)
+			// AsciiDoc passthrough `+name+` that downdoc preserved inside backticks
+			// (e.g. ``+IERC7984Receiver+``) — strip the leading/trailing + signs.
+			// Run before the code-aware split below so we can match across the
+			// backticks; restricted to identifier-like content so legitimate
+			// `a + b` style code is left alone.
+			mdContent = mdContent.replace(/`\+([^\s`+]+)\+`/g, "`$1`");
+
+			// AsciiDoc inline mailto: `mailto:URL[label]` → `[label](mailto:URL)`
+			// Run before the code-aware split since mailto in code blocks is
+			// rare and would render fine either way.
+			mdContent = mdContent.replace(
+				/mailto:([^\s[]+)\[([^\]]+)\]/g,
+				"[$2](mailto:$1)",
+			);
+
+			// Code-aware processing: skip triple-backtick blocks and inline code.
+			// Inside non-code regions:
+			//  - ++text++ → `text` (AsciiDoc passthrough monospace, single-line,
+			//    identifier-like content so we don't mangle Solidity ++i in code
+			//    blocks that downdoc may have left fenced incorrectly)
+			//  - bare < before digit/whitespace-word → &lt; (MDX-safe, e.g.
+			//    "<1 share", "< 0x80")
+			const codeSplit = mdContent.split(/(```[\s\S]*?```|`[^`\n]*`)/g);
+			mdContent = codeSplit
+				.map((part, idx) => {
+					if (idx % 2 === 1) return part;
+					return part
+						.replace(/\+\+([^+\n]+)\+\+/g, "`$1`")
+						.replace(/(<)(\s+\w|\d)/g, "&lt;$2");
+				})
 				.join("");
 			// Extract title
 			const headerMatch = mdContent.match(/^#+\s+(.+)$/m);