chore: touchup docs

content/20.api-reference/10.conventions.md

@@ -1,5 +1,6 @@
 ---
 title: Conventions
+description: Formatting conventions and references for use with zkSync Era API docs.
 ---
 
 ## Hex value encoding

content/20.api-reference/20.zks-rpc.md

@@ -8,8 +8,6 @@ zkSync Era provides a suite of JSON-RPC API methods designed for seamless intera
 These methods offer developers the tools needed to integrate their applications with zkSync Era's features,
 enhancing the capability to perform transactions, query network data, and interact with smart contracts efficiently.
 
-Below, we outline the key methods within the `zks_` namespace, each tailored for specific operations within zkSync Era.
-
 ## `zks_estimateFee`
 
 Estimates the fee for a given call request.

content/20.api-reference/30.debug-rpc.md

@@ -1,11 +1,9 @@
 ---
 title: Debug JSON-RPC API
-description:
+description: Methods useful for debugging purposes with zkSync Era.
 github: https://github.com/matter-labs/zksync-era/blob/main/core/lib/web3_decl/src/namespaces/debug.rs
 ---
 
-Here you can find the JSON-RPC API methods for the `debug_` namespace. These methods are useful for debugging purposes.
-
 ## `debug_traceBlockByHash`
 
 Traces all calls made from a specific block by its L2 hash.
@@ -14,7 +12,7 @@ Traces all calls made from a specific block by its L2 hash.
 
 1. **DATA, 32 bytes** - hash defining the L2 block.
 1. **TracerConfig** - Optional configuration for tracing. Refer to the
-[TraceConfig documentation](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#traceconfig) for more details.
+:external-link{text="TraceConfig documentation" href="https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#traceconfig"} for more details.
 
 #### Returns
 
@@ -70,7 +68,7 @@ Traces all calls made from a specific block by its L2 block number.
 
 1. **QUANTITY, 8 bytes | TAG** - The number of the block to trace. This can be a hex-encoded number or one of the strings "earliest", "latest", or "pending".
 1. **TracerConfig** - Optional configuration for tracing. Refer to the
-[TraceConfig documentation](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#traceconfig) for more details.
+:external-link{text="TraceConfig documentation" href="https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#traceconfig"} for more details.
 
 #### Returns
 
@@ -128,7 +126,7 @@ Traces a call made at a specific block, by block number or hash.
 1. **CallRequest** - The call request to trace, containing fields like `from`, `to`, `data`, and optionally `gas`, `gasPrice`, and `value`.
 1. **DATA, 32 bytes | QUANTITY, 8 bytes** - Optional. The block identifier, which can be a block number as a hex-encoded number or a block hash.
 If not specified, the latest block is used.
-1. **TracerConfig** - Optional. Configuration options for the trace. For more details, refer to the [TraceConfig documentation](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#traceconfig).
+1. **TracerConfig** - Optional. Configuration options for the trace. For more details, refer to the :external-link{text="TraceConfig documentation" href="https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#traceconfig"}.
 
 #### Returns
 
@@ -183,13 +181,13 @@ curl --request POST \
 
 ## `debug_traceTransaction`
 
-Uses the <a href="https://geth.ethereum.org/docs/developers/evm-tracing/built-in-tracers#call-tracer" target="_block">EVM's `callTracer`</a>
+Uses the :external-link{text="EVM's `callTracer`" href="https://geth.ethereum.org/docs/developers/evm-tracing/built-in-tracers#call-tracer"}
 to return a debug trace of a specific transaction given by its transaction hash.
 
 #### Parameters
 
 1. **DATA, 32 bytes** - The 32-byte hash of the transaction to trace.
-1. **TracerConfig** - Optional. Configuration options for the trace. For more details, refer to the [TraceConfig documentation](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#traceconfig).
+1. **TracerConfig** - Optional. Configuration options for the trace. For more details, refer to the :external-link{text="TraceConfig documentation" href="https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#traceconfig"}.
 
 #### Returns
 

content/20.api-reference/35.ethereum-rpc.md

@@ -1,10 +1,9 @@
 ---
 title: Ethereum JSON-RPC API
-description:
+description: JSON-RPC API methods for the eth_ namespace for zkSync Era.
 ---
 
-zkSync Era supports the standard <a href="https://ethereum.org/en/developers/docs/apis/json-rpc/" target="_blank">Ethereum JSON-RPC API</a>.
-Here you can find the JSON-RPC API methods for the `eth_` namespace.
+zkSync Era supports the standard :external-link{text="Ethereum JSON-RPC API" href="https://ethereum.org/en/developers/docs/apis/json-rpc/"}.
 
 ## `eth_chainId`
 
@@ -1212,7 +1211,7 @@ contractAddress : DATA, 20 Bytes - The contract address created, if the transact
 - **logsBloom**: DATA, 256 Bytes - Bloom filter for light clients to quickly retrieve related logs.
 - **type**: QUANTITY - integer of the transaction type, 0x0 for legacy transactions, 0x1 for access list types, 0x2 for dynamic fees.
 
-It also returns either :
+It also returns either:
 
 - **root**: DATA 32 -  bytes of post-transaction stateroot (pre Byzantium)
 - **status**: QUANTITY - either `0x1` (success) or `0x0` (failure)

content/20.api-reference/40.pub-sub-rpc.md

@@ -1,11 +1,10 @@
 ---
 title: PubSub JSON-RPC API
-description:
+description: Methods to subscribe/unsubscribe to events and receive notifications on zkSync Era.
 ---
 
 Clients can subscribe to specific events and receive notifications,
-thus avoiding the need to poll. zkSync is fully compatible with
-<a href="https://geth.ethereum.org/docs/interacting-with-geth/rpc/pubsub" target="_blank">Geth's pubsub API</a>,
+thus avoiding the need to poll. zkSync is fully compatible with :external-link{text="Geth's pubsub API" href="https://geth.ethereum.org/docs/interacting-with-geth/rpc/pubsub"},
 except for the `syncing` subscription.
 
 The WebSocket URL is `wss://mainnet.era.zksync.io/ws`
@@ -16,16 +15,13 @@ Creates a new subscription for events.
 
 #### Parameters
 
-| **Parameter**        | **Type**    | **Description**         |
-|----------------------|-------------|----------------------|
-| `subscriptionName`   | `String`    | Name of the subscription. Valid names include "newHeads" for new block headers, "logs" for new log entries, and others depending on the client's capabilities. |
-| `options`            | `Object`    | Optional filter conditions for the subscription, applicable for subscriptions like "logs" where specific event criteria can be set. |
+1. **String** - Name of the subscription. Valid names include "newHeads" for new block headers, "logs" for new log entries,
+and others depending on the client's capabilities.
+1. **Object** - (Optional) Filter conditions for the subscription, applicable for subscriptions like "logs" where specific event criteria can be set.
 
 #### Returns
 
-| **Field** | **Type** | **Description**                                      |
-|-----------|----------|------------------------------------------------------|
-| `result`  | `DATA` | A subscription ID used to identify and manage the subscription. |
+**DATA** - A subscription ID used to identify and manage the subscription.
 
 #### Example Request
 
@@ -56,15 +52,11 @@ Cancels an existing subscription.
 
 #### Parameters
 
-| **Parameter**       | **Type**    | **Description**      |
-|---------------------|-------------|-----------------|
-| `subscriptionId`    | `DATA`    | The ID of the subscription to cancel, as returned by `eth_subscribe`. |
+1. **DATA** - The ID of the subscription to cancel, as returned by `eth_subscribe`.
 
 #### Returns
 
-| **Field** | **Type**    |    **Description**         |
-|-----------|-------------|------------------|
-| `result`  | `boolean`   | `true` if the subscription was successfully cancelled, `false` otherwise. |
+**Boolean** - `true` if the subscription was successfully cancelled, `false` otherwise.
 
 #### Example Request
 

content/20.api-reference/_partials/_trace-object.md

@@ -5,18 +5,18 @@ title: Trace Object
 #### Trace Object
 
 ::collapsible
-| **Field**       | **Type**        | **Description** |
-|-----------------|-----------------|-----------------|
-| `type`          | `String`        | The type of operation (e.g., `Call`, `Create`, etc.), indicating the nature of the trace. |
-| `from`          | `DATA, 20 bytes`        | The address of the account that initiated the operation. |
-| `to`            | `DATA, 20 bytes`        | The recipient address of the call. For `Create` operations, this field is absent as the contract being created doesn't have an address until after the transaction completes. |
-| `gas`           | `QUANTITY, 32 bytes`        | The amount of gas provided for the operation. |
-| `gasUsed`       | `QUANTITY, 32 bytes`        | The amount of gas used by the operation. |
-| `value`         | `QUANTITY, 32 bytes`        | The amount of Ether transferred during the operation. |
-| `output`        | `DATA`        | The output from the operation. For operations that don't return data or failed, this is typically `0x`. |
-| `input`         | `DATA`        | The data sent into the call or contract creation. |
-| `error`         | `String`        | An error message if the operation failed. |
-| `revertReason`  | `String`        | The reason provided by a `revert` operation, if applicable. |
-| `calls`         | `Array<Object>` | An array of nested calls made by this operation. This field is recursive, containing further traces of calls made by the traced operation. |
 
+- **type**: String - The type of operation (e.g., `Call`, `Create`, etc.), indicating the nature of the trace.
+- **from**: DATA, 20 bytes - address of the account that initiated the operation.
+- **to**: DATA, 20 bytes - recipient address of the call.
+For `Create` operations, this field is absent as the contract being created doesn't have an address until after the transaction completes.
+- **gas**: QUANTITY, 32 bytes - amount of gas provided for the operation.
+- **gasUsed**: QUANTITY, 32 bytes - amount of gas used by the operation.
+- **value**: QUANTITY, 32 bytes - amount of Ether transferred during the operation.
+- **output**: DATA - output from the operation. For operations that don't return data or failed, this is typically `0x`.
+- **input**: DATA - data sent into the call or contract creation.
+- **error**: String - error message if the operation failed.
+- **revertReason**: String - reason provided by a `revert` operation, if applicable.
+- **calls**: Array\<Object\> - array of nested calls made by this operation. This field is recursive,
+containing further traces of calls made by the traced operation.
 ::