Merge branch 'next' into merge-train/avm

Author: AztecBot

.github/workflows/nightly-docs-release.yml

@@ -130,14 +130,15 @@ jobs:
       - name: Create Aztec nightly docs version (Developer docs only)
         working-directory: ./docs
         run: |
-          # Set the commit tag for version macros
+          # Set the commit tag and release type for version macros
           export COMMIT_TAG=${{ env.NIGHTLY_TAG }}
+          export RELEASE_TYPE=nightly
 
           # Install dependencies
           yarn install
 
           # Build docs to ensure everything works
-          COMMIT_TAG=${{ env.NIGHTLY_TAG }} yarn build
+          COMMIT_TAG=${{ env.NIGHTLY_TAG }} RELEASE_TYPE=nightly yarn build
 
           # Create the versioned docs for Developer docs only
           # Network docs have separate versions for testnet/ignition releases

docs/CLAUDE.md

@@ -27,7 +27,8 @@ The documentation uses a **preprocessing system** that:
 
 - Pulls code from source files using `#include_code` macros
 - Generates auto-documentation from TypeScript/JavaScript sources
-- Processes macros like `#include_aztec_version` and `#include_testnet_version`
+- Processes version macros (`#release_version`, `#release_network`, `#include_aztec_version`, etc.)
+- Processes conditional content blocks (`#if`/`#elif`/`#else`/`#endif`)
 - Outputs to `processed-docs/` folder (used only in production builds)
 
 For development:
@@ -36,6 +37,52 @@ For development:
 - `yarn start` - Runs preprocessing once at startup and serves from source directories
 - **Important**: Hot reloading is NOT available - you must restart the dev server to see changes
 
+### Preprocessing Environment Variables
+
+The preprocessing system uses these environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `RELEASE_TYPE` | Release type: `nightly`, `devnet`, `testnet`, `mainnet`, `ignition` | `nightly` |
+| `NIGHTLY_TAG` | Version for nightly builds (falls back to `COMMIT_TAG`) | `0.0.0-nightly.0` |
+| `DEVNET_TAG` | Version for devnet builds | `3.0.0-devnet.5` |
+| `TESTNET_TAG` | Version for testnet builds | `2.1.9` |
+| `MAINNET_TAG` | Version for mainnet/ignition builds | `2.1.9` |
+| `COMMIT_TAG` | Legacy variable, used as fallback for `NIGHTLY_TAG` | `next` |
+
+### Preprocessing Macros
+
+**Release-type-aware macros:**
+- `#release_version` - Resolves to the version for the current `RELEASE_TYPE`:
+  - `nightly` → `NIGHTLY_TAG`, `devnet` → `DEVNET_TAG`, `testnet` → `TESTNET_TAG`, `mainnet`/`ignition` → `MAINNET_TAG`
+- `#release_network` - Resolves to the network name for CLI `--network` flag:
+  - `nightly` → `local-network`, `devnet` → `devnet`, `testnet` → `testnet`, `mainnet`/`ignition` → `mainnet`
+
+**Legacy macros:**
+- `#include_aztec_version` - Uses `COMMIT_TAG`
+- `#include_devnet_version`, `#include_testnet_version`, `#include_mainnet_version` - Version-specific macros
+
+### Conditional Content
+
+Use conditional blocks to show content only for specific release types:
+
+```markdown
+#if(devnet)
+Content for devnet docs
+#elif(testnet)
+Content for testnet docs
+#else
+Default content
+#endif
+```
+
+**Supported conditions** (matching `RELEASE_TYPE` values): `nightly`, `devnet`, `testnet`, `mainnet`, `ignition`
+
+**Notes:**
+- Conditional blocks are processed before version macro substitution (so you can use version macros inside conditionals)
+- Nested conditionals are not supported
+- The `#else` block is optional
+
 ## Documentation Architecture
 
 ### Key Directories
@@ -67,7 +114,7 @@ Uses Docusaurus multi-instance versioning with separate version tracks:
 - **Developer docs**: Versions in `developer_versions.json`, stored in `developer_versioned_docs/`
 - **Network docs**: Versions in `network_versions.json`, stored in `network_versioned_docs/`
 - Each docs instance has its own version dropdown in the navbar
-- Macros (`#include_code`, `#include_aztec_version`, etc.) only work in source folders, not in versioned copies
+- Preprocessing macros (`#include_code`, `#release_version`, conditionals, etc.) only work in source folders, not in versioned copies
 - Create new versions with: `yarn docusaurus docs:version:<instance-id> <version>`
 
 ## Documentation Review Standards
@@ -255,5 +302,5 @@ Approved external documentation sources:
 - Flag any content that might need subject matter expert review
 - Suggest improvements even if they go beyond pure editing
 
-Last updated: 2025-15-08
-Version: 1.1
+Last updated: 2025-12-24
+Version: 1.2

docs/README.md

@@ -51,13 +51,15 @@ The way docs builds work is the following:
 - [The main CI workflow](../.github/workflows/ci3.yml) runs on pull requests and builds the dependencies and the docs, giving you a preview to check that everything is correct. You can also trigger docs CI specifically with the `ci-docs` label on a PR.
 - [The nightly docs workflow](../.github/workflows/nightly-docs-release.yml) runs daily to create versioned documentation for nightly releases, automatically cutting a new version of the docs for the latest nightly tag
 
-The `#include_aztec_version` and `#include_code` macros look for the version tag in an environment variable `COMMIT_TAG`, so you can build the docs specifying a version with the following command (e.g. for v3.0.0-devnet.5):
+The preprocessing macros use environment variables to determine version numbers. For nightly builds, set `NIGHTLY_TAG` (or `COMMIT_TAG` for backwards compatibility):
 
 ```bash
-COMMIT_TAG=v3.0.0-devnet.5 yarn build
+NIGHTLY_TAG=v3.0.0-nightly.20251218 yarn build
 ```
 
-You can add the aztec version to a docs page without the `v` prefix with `#include_version_without_prefix`, so COMMIT_TAG `v3.0.0-devnet.5` will render as `3.0.0-devnet.5`.
+For other release types, use `RELEASE_TYPE` with the corresponding tag variable (see [RELEASE_TYPE Environment Variable](#release_type-environment-variable) for details).
+
+The legacy `#include_aztec_version` macro uses `COMMIT_TAG`, while `#include_version_without_prefix` strips the `v` prefix (e.g., `v3.0.0-devnet.5` renders as `3.0.0-devnet.5`).
 
 ### How do I change the versions that show in the website
 
@@ -318,6 +320,94 @@ This value may be different from the `#include_aztec_version` macro, since the t
 This macro will be replaced inline with the provided devnet version. This value is sourced from the `DEVNET_TAG` environment variable when running `yarn build` (e.g. `DEVNET_TAG=3.0.0-devnet.4 yarn build`). If not specified, it defaults to `3.0.0-devnet.4`.
 This value may be different from both `#include_aztec_version` and `#include_testnet_version` macros, since the devnet version represents a separate development network release.
 
+### `#include_mainnet_version`
+
+This macro will be replaced inline with the provided mainnet version. This value is sourced from the `MAINNET_TAG` environment variable when running `yarn build` (e.g. `MAINNET_TAG=2.1.9 yarn build`). If not specified, it defaults to `2.1.9`.
+This value is used for mainnet and ignition releases.
+
+### `#release_version`
+
+This macro is release-type-aware and automatically resolves to the appropriate version based on the `RELEASE_TYPE` environment variable:
+
+| RELEASE_TYPE | Resolves to | Example |
+|--------------|-------------|---------|
+| nightly | `NIGHTLY_TAG` (falls back to `COMMIT_TAG`) | `3.0.0-nightly.20251218` |
+| devnet | `DEVNET_TAG` | `3.0.0-devnet.5` |
+| testnet | `TESTNET_TAG` | `2.1.9` |
+| mainnet | `MAINNET_TAG` | `2.1.9` |
+| ignition | `MAINNET_TAG` | `2.1.9` |
+
+Usage: `aztecprotocol/aztec:#release_version`
+
+### `#release_network`
+
+This macro resolves to the network name for use with the `--network` CLI flag:
+
+| RELEASE_TYPE | Resolves to |
+|--------------|-------------|
+| nightly | `local-network` |
+| devnet | `devnet` |
+| testnet | `testnet` |
+| mainnet | `mainnet` |
+| ignition | `mainnet` |
+
+Usage: `--network #release_network`
+
+### `RELEASE_TYPE` Environment Variable
+
+The `RELEASE_TYPE` environment variable controls which release type the documentation is being built for. Valid values are:
+
+- `nightly` (default) - For nightly developer docs releases
+- `devnet` - For devnet releases
+- `testnet` - For testnet releases
+- `mainnet` - For mainnet releases
+- `ignition` - For ignition releases (treated as mainnet)
+
+Example build commands:
+```bash
+# Build for nightly (default)
+NIGHTLY_TAG=v3.0.0-nightly.20251218 yarn build
+
+# Build for devnet
+RELEASE_TYPE=devnet DEVNET_TAG=3.0.0-devnet.5 yarn build
+
+# Build for testnet
+RELEASE_TYPE=testnet TESTNET_TAG=2.1.9 yarn build
+
+# Build for ignition/mainnet
+RELEASE_TYPE=ignition MAINNET_TAG=2.1.9 yarn build
+```
+
+### Conditional Content
+
+You can include content that only appears for specific release types using conditional blocks:
+
+```markdown
+#if(nightly)
+Content that only appears in nightly docs
+#elif(devnet)
+Content that only appears in devnet docs
+#elif(testnet)
+Content that only appears in testnet docs
+#elif(mainnet)
+Content that only appears in mainnet/ignition docs
+#else
+Default content if no condition matches
+#endif
+```
+
+**Supported conditions** (matching `RELEASE_TYPE` values):
+- `nightly` - True when `RELEASE_TYPE=nightly`
+- `devnet` - True when `RELEASE_TYPE=devnet`
+- `testnet` - True when `RELEASE_TYPE=testnet`
+- `mainnet` - True when `RELEASE_TYPE=mainnet` or `RELEASE_TYPE=ignition`
+- `ignition` - Alias for `mainnet`
+
+**Notes:**
+- Conditional blocks are processed before version macro substitution, so you can use version macros inside conditionals
+- Nested conditionals are not supported
+- The `else` block is optional
+
 ## Viewing (outdated) protocol specs
 
 The protocol specs pages are outdated, but it may still be useful to view them in some cases.

docs/docs-network/operation/monitoring_example_troubleshooting.md

@@ -12,7 +12,7 @@ Here's a complete example with all monitoring components integrated with your Az
 services:
   # Your Aztec node (example for full node)
   aztec-node:
-    image: "aztecprotocol/aztec:2.1.9"
+    image: "aztecprotocol/aztec:#release_version"
     container_name: "aztec-node"
     ports:
       - ${AZTEC_PORT}:${AZTEC_PORT}
@@ -36,7 +36,7 @@ services:
       start
       --node
       --archiver
-      --network testnet
+      --network #release_network
     networks:
       - aztec
     restart: always

docs/docs-network/prerequisites.md

@@ -63,7 +63,7 @@ bash -i <(curl -s https://install.aztec.network)
 Install the correct version for the current network:
 
 ```bash
-aztec-up #include_testnet_version
+aztec-up #release_version
 ```
 
 ### L1 Ethereum Node Access

docs/docs-network/setup/bootnode_operation.md

@@ -58,7 +58,7 @@ Create a `docker-compose.yml` file for your bootnode:
 ```yaml
 services:
   aztec-bootnode:
-    image: "aztecprotocol/aztec:#include_testnet_version"
+    image: "aztecprotocol/aztec:#release_version"
     container_name: "aztec-bootnode"
     ports:
       - ${P2P_PORT}:${P2P_PORT}

docs/docs-network/setup/building_from_source.md

@@ -45,10 +45,10 @@ cd aztec-packages
 
 ### Step 2: Check Out a Version Tag
 
-Check out the version tag you want to build. For example, to build version #include_testnet_version:
+Check out the version tag you want to build. For example, to build version #release_version:
 
 ```bash
-git checkout v#include_testnet_version
+git checkout v#release_version
 ```
 
 :::tip
@@ -150,11 +150,11 @@ The tag `aztecprotocol/release-image-base` must match exactly—the Dockerfile i
 Build the final node image, combining the runtime environment (Step 5) with your compiled code (Step 4):
 
 ```bash
-docker build -f release-image/Dockerfile --build-arg VERSION=#include_testnet_version -t aztec-local:#include_testnet_version .
+docker build -f release-image/Dockerfile --build-arg VERSION=#release_version -t aztec-local:#release_version .
 ```
 
 :::tip
-The tag `aztec-local:#include_testnet_version` avoids conflicts with the official Docker Hub image and clearly indicates this is a locally-built version.
+The tag `aztec-local:#release_version` avoids conflicts with the official Docker Hub image and clearly indicates this is a locally-built version.
 :::
 
 **Build arguments:**
@@ -180,21 +180,21 @@ You should see your image listed:
 
 ```
 REPOSITORY      TAG       IMAGE ID       CREATED        SIZE
-aztec-local     #include_testnet_version     abc123def456   2 minutes ago  2.5GB
+aztec-local     #release_version     abc123def456   2 minutes ago  2.5GB
 ```
 
 ### Verify Version
 
 ```bash
-docker run --rm aztec-local:#include_testnet_version --version
+docker run --rm aztec-local:#release_version --version
 ```
 
-Should display version #include_testnet_version.
+Should display version #release_version.
 
 ### Test Basic Functionality
 
 ```bash
-docker run --rm aztec-local:#include_testnet_version --help
+docker run --rm aztec-local:#release_version --help
 ```
 
 Should display CLI help information without errors.
@@ -256,7 +256,7 @@ If all checks pass, your image is ready to use.
 
 **Solutions**:
 - Ensure you used `--build-arg VERSION=X.Y.Z` when building the release image
-- The version should match the git tag without the 'v' prefix (e.g., `#include_testnet_version` not `v#include_testnet_version`)
+- The version should match the git tag without the 'v' prefix (e.g., `#release_version` not `v#release_version`)
 
 ## Using Your Custom Build
 
@@ -267,7 +267,7 @@ Use your locally-built image with any node setup method. For Docker Compose, upd
 ```yaml
 services:
   aztec-node:
-    image: "aztec-local:#include_testnet_version"
+    image: "aztec-local:#release_version"
     # ... rest of configuration
 ```
 
@@ -278,7 +278,7 @@ See [Running a Full Node](./running_a_node.md) for complete setup instructions.
 Run the Aztec CLI directly from your custom image:
 
 ```bash
-docker run --rm aztec-local:#include_testnet_version --version
+docker run --rm aztec-local:#release_version --version
 ```
 
 ## Alternative Approaches

docs/docs-network/setup/running_a_node.md

@@ -25,7 +25,7 @@ These requirements are subject to change as the network throughput increases.
 
 **Before proceeding:** Ensure you've reviewed and completed the [prerequisites](../prerequisites.md).
 
-This setup includes only essential settings. The `--network testnet` flag applies network-specific defaults—see the [CLI reference](../reference/cli_reference.md) for all available configuration options.
+This setup includes only essential settings. The `--network #release_network` flag applies network-specific defaults—see the [CLI reference](../reference/cli_reference.md) for all available configuration options.
 
 ## Setup
 
@@ -72,7 +72,7 @@ Create a `docker-compose.yml` file in your `aztec-node` directory:
 ```yaml
 services:
   aztec-node:
-    image: "aztecprotocol/aztec:#include_testnet_version"
+    image: "aztecprotocol/aztec:#release_version"
     container_name: "aztec-node"
     ports:
       - ${AZTEC_PORT}:${AZTEC_PORT}
@@ -97,7 +97,7 @@ services:
       start
       --node
       --archiver
-      --network testnet
+      --network #release_network
     networks:
       - aztec
     restart: always