chore: finish up tooling docs

.vscode/snippets.code-snippets

@@ -15,6 +15,11 @@
   // 	],
   // 	"description": "Log output to console"
   // }
+  "ZK Snippet": {
+    "scope": "markdown",
+    "prefix": "@zk",
+    "body": ["%%zk_$1%%$0"],
+  },
   "External Link": {
     "scope": "markdown",
     "prefix": "@exlink",

content/40.tooling/00.zksync-block-explorers.md

@@ -3,21 +3,21 @@ title: Block Explorers
 description: Learn about the official and 3rd party resources for exploring the zkSync Era network.
 ---
 
-The :external-link{text="zkSync Era Block Explorer" href="https://explorer.zksync.io/"}
+The :external-link{text="zkSync Era Block Explorer" href="%%zk_mainnet_block_explorer_url%%"}
 details comprehensive data about transactions, blocks, batches, wallets, tokens, and smart contracts on the zkSync Era network.
 
 ## Block Explorer API
 
 We’ve developed the zkSync Era Block Explorer API for developers to access zkSync Era Block Explorer data directly via HTTP requests.
 
-- :external-link{text="Mainnet Block Explorer API" href="https://block-explorer-api.mainnet.zksync.io/docs"}
-- :external-link{text="Testnet Block Explorer API" href="https://block-explorer-api.sepolia.zksync.dev/docs"}
+- :external-link{text="Mainnet Block Explorer API" href="%%zk_mainnet_block_explorer_url%%/docs"}
+- :external-link{text="Testnet Block Explorer API" href="%%zk_testnet_block_explorer_url%%/docs"}
 
 The API provides various endpoints for many use cases you might want in your app.
 It is compatible with :external-link{text="Etherscan API" href="https://docs.etherscan.io/"},
 which makes it easy to transition your existing apps to zkSync Era network.
 
-Feel free to contribute and create issues and feature requests in :external-link{text="zkSync Era Block Explorer GitHub repo" href="https://github.com/matter-labs/block-explorer"}.
+Feel free to contribute and create issues and feature requests in :external-link{text="zkSync Era Block Explorer GitHub repo" href="%%zk_git_repo_block-explorer%%"}.
 
 ## Other block explorers
 

content/40.tooling/10.zksync-cli/00.overview.md

@@ -41,11 +41,11 @@ npm update -g zksync-cli
 
 ## Further Assistance
 
-Need help? Join our :external-link{text="GitHub Discussions" href="https://github.com/zkSync-Community-Hub/zksync-developers/discussions/"}
+Need help? Join our :external-link{text="GitHub Discussions" href="%%zk_git_repo_zksync-developers%%/discussions/"}
 to ask questions, share your experiences, and connect with the zkSync community.
 
 ## Source Code
 
-The :external-link{text="zkSync CLI project" href="https://github.com/matter-labs/zksync-cli"}
+The :external-link{text="zkSync CLI project" href="%%zk_git_repo_zksync-cli"}
 is open-source and available on GitHub under the MIT License.
 Feel free to contribute, report issues, or suggest new features to help us improve the tool for everyone.

content/40.tooling/10.zksync-cli/01.troubleshooting.md

@@ -10,6 +10,8 @@ Encountering issues with zkSync CLI? Here are some common problems and step-by-s
 If you try to use the `zksync-cli` command and receive the `command not found` message, double check if you
 have the package installed locally or were using the `npx zksync-cli` command.
 
+---
+
 ## `unknown command` Error
 
 If you encounter an `unknown command` error, follow these steps:
@@ -41,20 +43,26 @@ e. **Use the Latest Version**
 
 - As a quick fix, or if the above steps don't resolve the issue, use `npx zksync-cli@latest [command]`, for example, `npx zksync-cli@latest dev start`.
 
+---
+
 ## My version is outdated
 
 If `zksync-cli` is not running the latest version:
 
 - Refer to the [instructions for `unknown command` Error](/tooling/zksync-cli/troubleshooting#unknown-command-error)
 above to check and update your zkSync CLI version.
 
+---
+
 ## `command not found: npx` Error
 
 If you receive a `command not found: npx` error, it means Node.js is not installed or not correctly set up on your system:
 
 - Install Node.js from :external-link{text="the official website" href="https://nodejs.org/"}. This will also install `npm` and `npx`.
 - After installation, restart your terminal and try running `npx zksync-cli` again.
 
+---
+
 ## Other issues
 
-For all other issues, we encourage you to seek help or report them in our :external-link{text="GitHub Discussions" href="https://github.com/zkSync-Community-Hub/zksync-developers/discussions/new?category=general&title=[zksync-cli]%20<Title>"}.
+For all other issues, we encourage you to seek help or report them in our :external-link{text="GitHub Discussions" href="%%zk_git_repo_zksync-developers%%/discussions/new?category=general&title=[zksync-cli]%20<Title>"}.

content/40.tooling/10.zksync-cli/10.zksync-cli-dev.md

@@ -49,4 +49,4 @@ If modules malfunction, e.g., failing to start:
 1. Use `zksync-cli dev stop` to cease all operations.
 2. Reinstall the problematic module with `zksync-cli dev clean [module name]`.
 3. Restart with `zksync-cli dev start`. Check Docker container logs for detailed errors, accessible through Docker Desktop.
-4. Persisting issues? Please report them in our :external-link{text="GitHub discussions" href="https://github.com/zkSync-Community-Hub/zksync-developers/discussions/new?category=general&title=[zksync-cli]%20<Title>"}.
+4. Persisting issues? Please report them in our :external-link{text="GitHub discussions" href="%%zk_git_repo_zksync-developers%%/discussions/new?category=general&title=[zksync-cli]%20<Title>"}.

content/40.tooling/10.zksync-cli/20.zksync-cli-create.md

@@ -22,21 +22,21 @@ Ensure you have the following installed before you start:
 Fast-track your UI development with our frontend templates, supporting popular frameworks like Vue, React, Next.js, Nuxt, and Vite.
 Options include viem, ethers, web3modal, rainbowkit, and more, equipping you with the necessary tools for dApp development.
 
-:external-link{text="zksync-frontend-templates repo" href="https://github.com/matter-labs/zksync-frontend-templates#readme"}
+:external-link{text="zksync-frontend-templates repo" href="%%zk_git_repo_zksync-frontend-templates#readme"}
 
 ### Contracts
 
 For smart contract development, choose from templates designed for quick deployment and testing, compatible with Solidity or Vyper.
 Utilize tools like Hardhat to streamline your workflow.
 
-:external-link{text="zksync-contract-templates repo" href="https://github.com/matter-labs/zksync-contract-templates#readme"}
+:external-link{text="zksync-contract-templates repo" href="%%zk_git_repo_zksync-contract-templates%%#readme"}
 
 ### Scripting
 
 Enhance your project with Node.js scripting templates for automated interactions and advanced zkSync operations.
 Includes examples of wallet or contract interactions using viem, ethers, or web3.js.
 
-:external-link{text="zksync-scripting-templates repo" href="https://github.com/matter-labs/zksync-scripting-templates#readme"}
+:external-link{text="zksync-scripting-templates repo" href="%%zk_git_repo_zksync-scripting-templates%%#readme"}
 
 ## Using Templates
 

content/40.tooling/20.hardhat/10.getting-started.md

@@ -36,7 +36,7 @@ or the [vyper-example](https://github.com/matter-labs/hardhat-zksync/tree/main/e
 
 ## Prerequisites
 
-- Make sure your machine satisfies the :external-link{text="system requirements" href="https://github.com/matter-labs/era-compiler-solidity/tree/main#system-requirements"}.
+- Make sure your machine satisfies the :external-link{text="system requirements" href="%%zk_git_repo_era-compiler-solidity%%/tree/main#system-requirements"}.
 - You have Node installed and have `yarn` or `npm` package manager.
 - You are already familiar with deploying smart contracts on zkSync.
 <!-- TODO: update link to proper guide -->
@@ -103,7 +103,7 @@ The `zksolc` block contains the minimal configuration for the compiler.
 
 ```ts
 zksolc: {
-  version: "latest", // Uses latest available in https://github.com/matter-labs/zksolc-bin/
+  version: "latest", // Uses latest available in %%zk_git_repo_zksolc-bin%%
   settings: {},
 },
 ```
@@ -120,7 +120,7 @@ The `zkvyper` block contains the minimal configuration for the compiler.
 
 ```ts
 zkvyper: {
-  version: "latest", // Uses latest available in https://github.com/matter-labs/zkvyper-bin/
+  version: "latest", // Uses latest available in %%zk_git_repo_zkvyper-bin%%
   settings: {},
 },
 ```
@@ -140,7 +140,7 @@ const zkSyncTestnet =
       }
     : {
         url: "%%zk_testnet_rpc_url%%",
-        ethNetwork: "sepolia",
+        ethNetwork: "%%zk_testnet_identifier%%",
         zksync: true,
       };
 ```

content/40.tooling/20.hardhat/100.hardhat-zksync-ethers.md

@@ -75,7 +75,7 @@ interface FactoryDeps {
 interface ZkSyncArtifact extends Artifact {
   // List of factory dependencies of a contract.
   factoryDeps: FactoryDeps;
-  // Mapping from the bytecode to the zkEVM assembly (used for tracing).
+  // Mapping from the bytecode to the %%zk_zkevm_label%% assembly (used for tracing).
   sourceMapping: string;
 }
 

content/40.tooling/20.hardhat/120.hardhat-zksync-node.md

@@ -95,7 +95,7 @@ check out the [In-memory node documentation](../../test-and-debug//era-test-node
 ::callout{icon="i-heroicons-information-circle" color="blue"}
 **Supported APIs**:
 
-To see a list of all supported APIs, visit :external-link{text="this link" href="https://github.com/matter-labs/era-test-node/blob/main/SUPPORTED_APIS.md"}.
+To see a list of all supported APIs, visit :external-link{text="this link" href="%%zk_git_repo_era-test-node%%/blob/main/SUPPORTED_APIS.md"}.
 ::
 
 ## Running Hardhat's test Task with hardhat-zksync-node

content/40.tooling/20.hardhat/20.migrating-to-zksync.md

@@ -125,7 +125,7 @@ import "@matterlabs/hardhat-zksync-solc";
 
 const config: HardhatUserConfig = {
   zksolc: {
-    version: "latest", // Uses latest available in https://github.com/matter-labs/zksolc-bin/
+    version: "latest", // Uses latest available in %%zk_git_repo_zksolc-bin%%
     settings: {},
   },
   defaultNetwork: "zkSyncTestnet",

content/40.tooling/20.hardhat/30.compiling-libraries.md

@@ -11,7 +11,7 @@ i.e. does not use external calls to access the library methods and uses the code
 
 - _Non-inlinable_. The ones that have at least one `public` or `external` method.
 While they may be inlined by the Solidity compiler, they are not inlined when compiled to Yul representation.
-Since Yul is an intermediate step when compiling to %%zk_evm_label%% bytecode, this means that these libraries can not be inlined by the zkSync compiler.
+Since Yul is an intermediate step when compiling to %%zk_zkevm_label%% bytecode, this means that these libraries can not be inlined by the zkSync compiler.
 
 **Practically this means that libraries with public methods need to be deployed separately
 and their addresses passed as an argument when compiling the main contract.**
@@ -67,6 +67,8 @@ If you try to create a project with these two files following the guidelines fro
 
 Following error:
 
+<!-- TODO: check that the links are up-to-date.
+Message is using era.zksync.io -->
 ```sh
 zksolc compiler detected missing libraries! For more details, visit: https://era.zksync.io/docs/tools/hardhat/compiling-libraries.html.
 To compile and deploy libraries, please run: `yarn hardhat deploy-zksync:libraries`
@@ -130,7 +132,7 @@ import "@matterlabs/hardhat-zksync-solc";
 
 module.exports = {
   zksolc: {
-    version: "latest", // Uses latest available in https://github.com/matter-labs/zksolc-bin/
+    version: "latest", // Uses latest available in %%zk_git_repo_zksolc-bin%%
     settings: {
       libraries: {
         "contracts/MiniMath.sol": {

content/40.tooling/20.hardhat/40.hardhat-zksync-solc.md

@@ -5,7 +5,7 @@ description:
 
 This plugin is used to provide a convenient interface for compiling Solidity smart contracts before deploying them to zkSync Era.
 
-Learn more about the latest updates in the :external-link{text="changelog" href="https://github.com/matter-labs/hardhat-zksync/blob/main/packages/hardhat-zksync-solc/CHANGELOG.md"}.
+Learn more about the latest updates in the :external-link{text="changelog" href="%%zk_git_repo_hardhat-zksync%%/blob/main/packages/hardhat-zksync-solc/CHANGELOG.md"}.
 
 ## Prerequisite
 
@@ -85,7 +85,8 @@ zksolc: {
 Compilers are no longer released as Docker images and its usage is no longer recommended.
 ::
 
-- `version` is the `zksolc` compiler version. Compiler versions can be found in [the following repository](https://github.com/matter-labs/zksolc-bin).
+- `version` is the `zksolc` compiler version.
+  Compiler versions can be found in :external-link{text="the following repository" href="%%zk_git_repo_zksolc-bin%%"}.
 - `compilerSource` indicates the compiler source and can be either `binary` (default) or `docker` (deprecated).
 If there isn't a compiler binary already installed, the plugin will automatically download it.
 - `compilerPath` (optional) is a field with the path to the `zksolc` binary. By default, the binary in `$PATH` is used.
@@ -137,9 +138,10 @@ This approach is implemented to provide a caching mechanism, avoiding the risk o
 
 ### zkSync Era Solidity compiler
 
+<!-- TODO: update links -->
 Due to :external-link{text="the identified limitations" href="https://docs.zksync.io/zk-stack/components/compiler/toolchain/solidity.html#limitations"}
 of the :external-link{text="upstream Solidity compiler" href="https://github.com/ethereum/solidity"},
-our team has developed :external-link{text="a new edition" href="https://github.com/matter-labs/era-solidity"}
+our team has developed :external-link{text="a new edition" href="%%zk_git_repo_era-solidity%%"}
 of the compiler, which effectively addresses and resolves these constraints.
 
 For usage of EraVM compiler, `eraVersion` should be added inside `solidity` property in the `hardhat.config.ts` file:

content/40.tooling/20.hardhat/50.hardhat-zksync-vyper.md

@@ -6,7 +6,7 @@ description:
 The :external-link{text="@matterlabs/hardhat-zksync-vyper" href="https://www.npmjs.com/package/@matterlabs/hardhat-zksync-vyper"} plugin
 provides an interface for compiling Vyper smart contracts before deploying them to zkSync Era.
 
-Learn more about the latest updates in the :external-link{text="changelog" href="https://github.com/matter-labs/hardhat-zksync/blob/main/packages/hardhat-zksync-vyper/CHANGELOG.md"}.
+Learn more about the latest updates in the :external-link{text="changelog" href="%%zk_git_repo_hardhat-zksync%%/blob/main/packages/hardhat-zksync-vyper/CHANGELOG.md"}.
 
 ## Prerequisite
 
@@ -44,7 +44,7 @@ Any configuration parameters should be added inside a `zkvyper` property in the
 
 ```ts
 zkvyper: {
-    version: "latest", // Uses latest available in https://github.com/matter-labs/zkvyper-bin/
+    version: "latest", // Uses latest available in %%zk_git_repo_zkvyper-bin%%
     settings: {
       // compilerPath: "zkvyper", // optional field with the path to the `zkvyper` binary.
       libraries: {}, // optional. References to non-inlinable libraries
@@ -65,7 +65,7 @@ Compilers are no longer released as Docker images and its usage is no longer rec
 ::
 
 - `version`: The `zkvyper` compiler version. Default value is `latest`.
-Find the latest compiler versions in the :external-link{text="zkvyper repo" href="https://github.com/matter-labs/zkvyper-bin"}.
+Find the latest compiler versions in the :external-link{text="zkvyper repo" href="%%zk_git_repo_zkvyper-bin%%"}.
 - `compilerSource`: Indicates the compiler source and can be either `binary`. (A `docker` option is no longer recommended).
 If there is no previous installation, the plugin automatically downloads one.
 - `optimizer` - Compiler optimizations:

content/40.tooling/20.hardhat/60.hardhat-zksync-deploy.md

@@ -175,7 +175,8 @@ class Deployer {
 
 To see an example script of how to use a `Deployer` class to deploy a contract, check out the [deployment section of the quickstart](./getting-started.md#compile-and-deploy-a-contract).
 
-::: note contractNameOrArtifact parameter within the deploy method
+::callout{icon="i-heroicons-information-circle" color="blue"}
+**contractNameOrArtifact parameter within the deploy method**
 
 In the method description, it's evident that `contractNameOrArtifact` can accept two types of objects.
 One type represents a loaded artifact, while the other type is a string representing a contract name,
@@ -192,7 +193,7 @@ const contract = await deployer.deploy(artifact);
 const contract = await deployer.deploy("ContractName");
 ```
 
-:::
+::
 
 ### Environment extensions
 

content/40.tooling/20.hardhat/80.hardhat-zksync-verify.md

@@ -5,7 +5,7 @@ description:
 
 This plugin is used to verify contracts on the zkSync Era network.
 
-:external-link{text="Changelog" href="https://github.com/matter-labs/hardhat-zksync/blob/main/packages/hardhat-zksync-verify/CHANGELOG.md"}
+:external-link{text="Changelog" href="%%zk_git_repo_hardhat-zksync%%/blob/main/packages/hardhat-zksync-verify/CHANGELOG.md"}
 
 ::callout{icon="i-heroicons-exclamation-triangle" color="amber"}
 **Unknown zksolc version**: If you encounter this error, it suggests that the backend verification system does not currently support

content/40.tooling/20.hardhat/90.hardhat-zksync-verify-vyper.md

@@ -23,7 +23,7 @@ and we do NOT recommend using it in the production environment.
 On the other hand, we are working on removing this limitation
 and we want to encourage you to give us your feedback on the plugin's functionalities, usability or possible improvements.
 Please start or engage in the discussion about it
-in our :external-link{text="Community Hub" href="https://github.com/zkSync-Community-Hub/zkync-developers/discussions"},
+in our :external-link{text="Community Hub" href="%%zk_git_repo_zksync-developers%%/discussions"},
 or open a Github issue in the :external-link{text="project's repository" href="https://github.com/matter-labs/hardhat-zksync/issues"}.
 ::
 

content/40.tooling/20.hardhat/other-plugins.md

@@ -4,12 +4,12 @@ description: Discover community plugins for Hardhat that work on zkSync Era.
 ---
 
 The following plugins were created by the community and tested on zkSync Era.
-Feel free to suggest new plugins by :external-link{text="creating a issue(feat request) at this page" href="https://github.com/matter-labs/hardhat-zksync/issues/new?assignees=&labels=feat&projects=&template=feature_report.md&title="}.
+Feel free to suggest new plugins by :external-link{text="creating a issue(feat request) at this page" href="%%zk_git_repo_hardhat-zksync%%/issues/new?assignees=&labels=feat&projects=&template=feature_report.md&title="}.
 
 ## Supported plugins
 
 ::callout{icon="i-heroicons-information-circle" color="blue"}
-Here is :external-link{text="a template project configured with all plugins mentioned below" href="https://github.com/matter-labs/era-hardhat-with-plugins"}.
+Here is :external-link{text="a template project configured with all plugins mentioned below" href="%%zk_git_repo_era-hardhat-with-plugins%%"}.
 You can use it as a starting template for your projects.
 ::
 

content/40.tooling/30.foundry/10.overview.md

@@ -13,13 +13,13 @@ deployment, testing, and interaction with smart contracts on zkSync.
 
 `foundry-zksync` is currently in its **alpha stage**, indicating ongoing development and potential for future enhancements.
 It is open-sourced, and contributions from the developer community are welcome.
-For more details and contributions, visit the :external-link{text="GitHub repository" href="https://github.com/matter-labs/foundry-zksync"}.
+For more details and contributions, visit the :external-link{text="GitHub repository" href="%%zk_git_repo_foundry-zksync%%"}.
 
 ## Features and Limitations
 
 ### Features
 
-`Foundry-zksync` offers a set of features designed to work with zkSync, providing a comprehensive toolkit for smart contract deployment and interaction:
+`foundry-zksync` offers a set of features designed to work with zkSync, providing a comprehensive toolkit for smart contract deployment and interaction:
 
 - **Smart Contract Deployment**: Easily deploy smart contracts to zkSync mainnet, testnet, or a local test node.
 - **Asset Bridging**: Bridge assets between L1 and L2, facilitating seamless transactions across layers.
@@ -40,6 +40,7 @@ While `foundry-zksync` is **alpha stage**, there are some limitations to be awar
 - **Specific Foundry Features**: Currently features such as `coverage`, `--gas-report` or `--verify` may not work as intended.
 We are actively working on providing support for these feature types.
 - **Compiling Libraries**: Compiling non-inlinable libraries requires deployment and adding to configuration.
+<!-- TODO: update link -->
 For more information please refer to :external-link{text="official docs" href="https://era.zksync.io/docs/tools/hardhat/compiling-libraries.html"}.
 
   ```toml

content/40.tooling/30.foundry/20.getting-started.md

@@ -99,7 +99,7 @@ Use `forge test --zksync` to run tests written for your smart contracts.
 
 ### Compilation with `forge build --zksync`
 
-`forge build --zksync` is used for compiling smart contracts into zkEVM bytecode.
+`forge build --zksync` is used for compiling smart contracts into %%zk_zkevm_label%% bytecode.
 The compiled files are stored in a structured directory at `<PROJECT-ROOT>/zkout/`.
 
 **Usage:**