Merge pull request #544 from algorandfoundation/docs/cleanup

mrcointreau · web-flow · commit 441f8da57889 · 2026-02-18T17:55:09.000+01:00
Add remark-github-alerts styles and remove duplicate headings
diff --git a/.nsprc b/.nsprc
@@ -9,9 +9,14 @@
     "notes": "@isaacs/brace-expansion is bundled inside npm - overrides cannot fix bundled deps, waiting for upstream fix",
     "expiry": "2026-03-01"
   },
-  "1112810": {
+  "1113214": {
     "active": true,
-    "notes": "npm cli vulnerability - bundled dependency, waiting for upstream fix",
-    "expiry": "2026-03-01"
+    "notes": "ajv ReDoS via $data option - dev dep via eslint, waiting for upstream eslint migration off ajv v6",
+    "expiry": "2026-03-18"
+  },
+  "1113249": {
+    "active": true,
+    "notes": "tar hardlink/symlink escape - bundled inside npm, waiting for npm release with tar >=7.5.8",
+    "expiry": "2026-03-18"
   }
 }
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
@@ -1,8 +1,8 @@
 // @ts-check
-import { defineConfig } from 'astro/config';
-import starlight from '@astrojs/starlight';
-import starlightTypeDoc, { typeDocSidebarGroup } from 'starlight-typedoc';
-import remarkGithubAlerts from 'remark-github-alerts';
+import starlight from '@astrojs/starlight'
+import { defineConfig } from 'astro/config'
+import remarkGithubAlerts from 'remark-github-alerts'
+import starlightTypeDoc, { typeDocSidebarGroup } from 'starlight-typedoc'
 
 // https://astro.build/config
 export default defineConfig({
@@ -14,6 +14,11 @@ export default defineConfig({
   integrations: [
     starlight({
       title: 'AlgoKit Utils TypeScript',
+      customCss: [
+        'remark-github-alerts/styles/github-colors-light.css',
+        'remark-github-alerts/styles/github-colors-dark-media.css',
+        'remark-github-alerts/styles/github-base.css',
+      ],
       social: [
         { icon: 'github', label: 'GitHub', href: 'https://github.com/algorandfoundation/algokit-utils-ts' },
         { icon: 'discord', label: 'Discord', href: 'https://discord.gg/algorand' },
@@ -108,4 +113,4 @@ export default defineConfig({
       ],
     }),
   ],
-});
+})
diff --git a/docs/src/content/docs/concepts/advanced/debugging.md b/docs/src/content/docs/concepts/advanced/debugging.md
@@ -1,10 +1,8 @@
 ---
 title: "Debugger"
-description: "The AlgoKit TypeScript Utilities package provides a set of debugging tools that can be used to simulate and trace transactions on the Algorand blockchain. These tools and methods are optimized for dev..."
+description: "The AlgoKit TypeScript Utilities package provides a set of debugging tools that can be used to simulate and trace transactions on the Algorand blockchain. These tools and methods are optimized for developers who are building applications on Algorand and need to test and debug their smart contracts via [AlgoKit AVM Debugger extension](https://github.com/algorandfoundation/algokit-avm-vscode-debugger)."
 ---
 
-# Debugger
-
 The AlgoKit TypeScript Utilities package provides a set of debugging tools that can be used to simulate and trace transactions on the Algorand blockchain. These tools and methods are optimized for developers who are building applications on Algorand and need to test and debug their smart contracts via [AlgoKit AVM Debugger extension](https://github.com/algorandfoundation/algokit-avm-vscode-debugger).
 
 ## Configuration
diff --git a/docs/src/content/docs/concepts/advanced/dispenser-client.md b/docs/src/content/docs/concepts/advanced/dispenser-client.md
@@ -1,10 +1,8 @@
 ---
 title: "TestNet Dispenser Client"
-description: "The TestNet Dispenser Client is a utility for interacting with the AlgoKit TestNet Dispenser API. It provides methods to fund an account, register a refund for a transaction, and get the current limit..."
+description: "The TestNet Dispenser Client is a utility for interacting with the AlgoKit TestNet Dispenser API. It provides methods to fund an account, register a refund for a transaction, and get the current limit for an account."
 ---
 
-# TestNet Dispenser Client
-
 The TestNet Dispenser Client is a utility for interacting with the AlgoKit TestNet Dispenser API. It provides methods to fund an account, register a refund for a transaction, and get the current limit for an account.
 
 ## Creating a Dispenser Client
diff --git a/docs/src/content/docs/concepts/advanced/event-emitter.md b/docs/src/content/docs/concepts/advanced/event-emitter.md
@@ -1,10 +1,8 @@
 ---
 title: "Event Emitter"
-description: "The Event Emitter is a capability provided by AlgoKit Utils that allows for asynchronous event handling of lifecycle events. It provides a flexible mechanism for emitting and listening to custom event..."
+description: "The Event Emitter is a capability provided by AlgoKit Utils that allows for asynchronous event handling of lifecycle events. It provides a flexible mechanism for emitting and listening to custom events, which can be particularly useful for debugging and extending functionality not available in the `algokit-utils-ts` package."
 ---
 
-# Event Emitter
-
 The Event Emitter is a capability provided by AlgoKit Utils that allows for asynchronous event handling of lifecycle events. It provides a flexible mechanism for emitting and listening to custom events, which can be particularly useful for debugging and extending functionality not available in the `algokit-utils-ts` package.
 
 ## `AsyncEventEmitter`
diff --git a/docs/src/content/docs/concepts/advanced/indexer.md b/docs/src/content/docs/concepts/advanced/indexer.md
@@ -1,10 +1,8 @@
 ---
 title: "Indexer lookups / searching"
-description: "Indexer lookups / searching is a higher-order use case capability provided by AlgoKit Utils that builds on top of the core capabilities. It provides type-safe indexer API wrappers (no more `Record<str..."
+description: "Indexer lookups / searching is a higher-order use case capability provided by AlgoKit Utils that builds on top of the core capabilities. It provides type-safe indexer API wrappers (no more `Record<string, any>` pain), including automatic pagination control."
 ---
 
-# Indexer lookups / searching
-
 Indexer lookups / searching is a higher-order use case capability provided by AlgoKit Utils that builds on top of the core capabilities. It provides type-safe indexer API wrappers (no more `Record<string, any>` pain), including automatic pagination control.
 
 To see some usage examples check out the `automated tests`.
diff --git a/docs/src/content/docs/concepts/advanced/modular-imports.md b/docs/src/content/docs/concepts/advanced/modular-imports.md
@@ -3,8 +3,6 @@ title: "Modular imports"
 description: "AlgoKit Utils is designed with a modular architecture that allows you to import only the functionality you need. This enables better tree-shaking and smaller bundle sizes for your applications."
 ---
 
-# Modular imports
-
 AlgoKit Utils is designed with a modular architecture that allows you to import only the functionality you need. This enables better tree-shaking and smaller bundle sizes for your applications.
 
 ## Package architecture
diff --git a/docs/src/content/docs/concepts/advanced/transaction-composer.md b/docs/src/content/docs/concepts/advanced/transaction-composer.md
@@ -3,8 +3,6 @@ title: "Transaction composer"
 description: "The `TransactionComposer` class allows you to easily compose one or more compliant Algorand transactions and execute and/or simulate them."
 ---
 
-# Transaction composer
-
 The `TransactionComposer` class allows you to easily compose one or more compliant Algorand transactions and execute and/or simulate them.
 
 It's the core of how the [`AlgorandClient`](../../core/algorand-client) class composes and sends transactions.
diff --git a/docs/src/content/docs/concepts/building/app-client.md b/docs/src/content/docs/concepts/building/app-client.md
@@ -1,10 +1,8 @@
 ---
 title: "App client and App factory"
-description: "App client and App factory are higher-order use case capabilities provided by AlgoKit Utils that builds on top of the core capabilities, particularly [App deployment](./app-deploy) and [App managem..."
+description: "App client and App factory are higher-order use case capabilities provided by AlgoKit Utils that builds on top of the core capabilities, particularly [App deployment](./app-deploy.md) and [App management](./app.md). They allow you to access high productivity application clients that work with [ARC-56](https://github.com/algorandfoundation/ARCs/pull/258) and [ARC-32](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0032.md) application spec defined smart contracts, which you can use to create, update, delete, deploy and call a smart contract and access state data for it."
 ---
 
-# App client and App factory
-
 > [!NOTE]
 > This page covers the untyped app client, but we recommend using [typed clients](../typed-app-clients), which will give you a better developer experience with strong typing and intellisense specific to the app itself.
 
diff --git a/docs/src/content/docs/concepts/building/app-deploy.md b/docs/src/content/docs/concepts/building/app-deploy.md
@@ -1,10 +1,8 @@
 ---
 title: "App deployment"
-description: "AlgoKit contains advanced smart contract deployment capabilities that allow you to have idempotent (safely retryable) deployment of a named app, including deploy-time immutability and permanence contr..."
+description: "AlgoKit contains advanced smart contract deployment capabilities that allow you to have idempotent (safely retryable) deployment of a named app, including deploy-time immutability and permanence control and TEAL template substitution. This allows you to control the smart contract development lifecycle of a single-instance app across multiple environments (e.g. LocalNet, TestNet, MainNet)."
 ---
 
-# App deployment
-
 AlgoKit contains advanced smart contract deployment capabilities that allow you to have idempotent (safely retryable) deployment of a named app, including deploy-time immutability and permanence control and TEAL template substitution. This allows you to control the smart contract development lifecycle of a single-instance app across multiple environments (e.g. LocalNet, TestNet, MainNet).
 
 It's optional to use this functionality, since you can construct your own deployment logic using create / update / delete calls and your own mechanism to maintaining app metadata (like app IDs etc.), but this capability is an opinionated out-of-the-box solution that takes care of the heavy lifting for you.
diff --git a/docs/src/content/docs/concepts/building/app.md b/docs/src/content/docs/concepts/building/app.md
@@ -1,10 +1,8 @@
 ---
 title: "App management"
-description: "App management is a higher-order use case capability provided by AlgoKit Utils that builds on top of the core capabilities. It allows you to create, update, delete, call (ABI and otherwise) smart cont..."
+description: "App management is a higher-order use case capability provided by AlgoKit Utils that builds on top of the core capabilities. It allows you to create, update, delete, call (ABI and otherwise) smart contract apps and the metadata associated with them (including state and boxes)."
 ---
 
-# App management
-
 App management is a higher-order use case capability provided by AlgoKit Utils that builds on top of the core capabilities. It allows you to create, update, delete, call (ABI and otherwise) smart contract apps and the metadata associated with them (including state and boxes).
 
 > [!TIP]
diff --git a/docs/src/content/docs/concepts/building/asset.md b/docs/src/content/docs/concepts/building/asset.md
@@ -3,8 +3,6 @@ title: "Assets"
 description: "The Algorand Standard Asset (asset) management functions include creating, opting in and transferring assets, which are fundamental to asset interaction in a blockchain environment."
 ---
 
-# Assets
-
 The Algorand Standard Asset (asset) management functions include creating, opting in and transferring assets, which are fundamental to asset interaction in a blockchain environment.
 
 To see some usage examples check out the `automated tests`.
diff --git a/docs/src/content/docs/concepts/building/testing.md b/docs/src/content/docs/concepts/building/testing.md
@@ -1,10 +1,8 @@
 ---
 title: "Automated testing"
-description: "Automated testing is a higher-order use case capability provided by AlgoKit Utils that builds on top of the core capabilities. It allows you to use terse, robust automated testing primitives that work..."
+description: "Automated testing is a higher-order use case capability provided by AlgoKit Utils that builds on top of the core capabilities. It allows you to use terse, robust automated testing primitives that work across any testing framework (including jest and vitest) to facilitate fixture management, quickly generating isolated and funded test accounts, transaction logging, indexer wait management and log capture."
 ---
 
-# Automated testing
-
 Automated testing is a higher-order use case capability provided by AlgoKit Utils that builds on top of the core capabilities. It allows you to use terse, robust automated testing primitives that work across any testing framework (including jest and vitest) to facilitate fixture management, quickly generating isolated and funded test accounts, transaction logging, indexer wait management and log capture.
 
 To see some usage examples check out the all of the [automated tests](../../src/) and the various \*.spec.ts files (AlgoKit Utils [dogfoods](https://en.wikipedia.org/wiki/Eating_your_own_dog_food) it's own testing library). Alternatively, you can see an example of using this library to test a smart contract with [the tests](https://github.com/algorandfoundation/nft_voting_tool/blob/main/src/algorand/smart_contracts/tests/voting.spec.ts) for the [on-chain voting tool](https://github.com/algorandfoundation/nft_voting_tool#readme).
diff --git a/docs/src/content/docs/concepts/building/transfer.md b/docs/src/content/docs/concepts/building/transfer.md
@@ -1,10 +1,8 @@
 ---
 title: "Algo transfers (payments)"
-description: "Algo transfers, or [payments](https://dev.algorand.co/concepts/transactions/types/#payment-transaction), is a higher-order use case capability provided by AlgoKit Utils that builds on top of the core ..."
+description: "Algo transfers, or [payments](https://dev.algorand.co/concepts/transactions/types/#payment-transaction), is a higher-order use case capability provided by AlgoKit Utils that builds on top of the core capabilities, particularly [Algo amount handling](../core/amount.md) and [Transaction management](../core/transaction.md). It allows you to easily initiate Algo transfers between accounts, including dispenser management and idempotent account funding."
 ---
 
-# Algo transfers (payments)
-
 Algo transfers, or [payments](https://dev.algorand.co/concepts/transactions/types/#payment-transaction), is a higher-order use case capability provided by AlgoKit Utils that builds on top of the core capabilities, particularly [Algo amount handling](../../core/amount) and [Transaction management](../../core/transaction). It allows you to easily initiate Algo transfers between accounts, including dispenser management and idempotent account funding.
 
 To see some usage examples check out the `automated tests`.
diff --git a/docs/src/content/docs/concepts/building/typed-app-clients.md b/docs/src/content/docs/concepts/building/typed-app-clients.md
@@ -1,10 +1,8 @@
 ---
 title: "Typed application clients"
-description: "Typed application clients are automatically generated, typed TypeScript deployment and invocation clients for smart contracts that have a defined [ARC-56](https://github.com/algorandfoundation/ARCs/pu..."
+description: "Typed application clients are automatically generated, typed TypeScript deployment and invocation clients for smart contracts that have a defined [ARC-56](https://github.com/algorandfoundation/ARCs/pull/258) or [ARC-32](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0032.md) application specification so that the development experience is easier with less upskill ramp-up and less deployment errors. These clients give you a type-safe, intellisense-driven experience for invoking the smart contract."
 ---
 
-# Typed application clients
-
 Typed application clients are automatically generated, typed TypeScript deployment and invocation clients for smart contracts that have a defined [ARC-56](https://github.com/algorandfoundation/ARCs/pull/258) or [ARC-32](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0032.md) application specification so that the development experience is easier with less upskill ramp-up and less deployment errors. These clients give you a type-safe, intellisense-driven experience for invoking the smart contract.
 
 Typed application clients are the recommended way of interacting with smart contracts. If you don't have/want a typed client, but have an ARC-56/ARC-32 app spec then you can use the [non-typed application clients](../app-client) and if you want to call a smart contract you don't have an app spec file for you can use the underlying [app management](../app) and [app deployment](../app-deploy) functionality to manually construct transactions.
diff --git a/docs/src/content/docs/concepts/core/account.md b/docs/src/content/docs/concepts/core/account.md
@@ -1,10 +1,8 @@
 ---
 title: "Account management"
-description: "Account management is one of the core capabilities provided by AlgoKit Utils. It allows you to create mnemonic, rekeyed, multisig, transaction signer, idempotent KMD and environment variable injected ..."
+description: "Account management is one of the core capabilities provided by AlgoKit Utils. It allows you to create mnemonic, rekeyed, multisig, transaction signer, idempotent KMD and environment variable injected accounts that can be used to sign transactions as well as representing a sender address at the same time. This significantly simplifies management of transaction signing."
 ---
 
-# Account management
-
 Account management is one of the core capabilities provided by AlgoKit Utils. It allows you to create mnemonic, rekeyed, multisig, transaction signer, idempotent KMD and environment variable injected accounts that can be used to sign transactions as well as representing a sender address at the same time. This significantly simplifies management of transaction signing.
 
 > [!TIP]
diff --git a/docs/src/content/docs/concepts/core/algorand-client.md b/docs/src/content/docs/concepts/core/algorand-client.md
@@ -3,8 +3,6 @@ title: "Algorand client"
 description: "`AlgorandClient` is a client class that brokers easy access to Algorand functionality. It's the `default entrypoint` into AlgoKit Utils functionality."
 ---
 
-# Algorand client
-
 `AlgorandClient` is a client class that brokers easy access to Algorand functionality. It's the `default entrypoint` into AlgoKit Utils functionality.
 
 The main entrypoint to the bulk of the functionality in AlgoKit Utils is the `AlgorandClient` class, most of the time you can get started by typing `AlgorandClient.` and choosing one of the static initialisation methods to create an [Algorand client](./), e.g.:
diff --git a/docs/src/content/docs/concepts/core/amount.md b/docs/src/content/docs/concepts/core/amount.md
@@ -3,8 +3,6 @@ title: "Algo amount handling"
 description: "Algo amount handling is one of the core capabilities provided by AlgoKit Utils. It allows you to reliably and tersely specify amounts of microAlgo and Algo and safely convert between them."
 ---
 
-# Algo amount handling
-
 Algo amount handling is one of the core capabilities provided by AlgoKit Utils. It allows you to reliably and tersely specify amounts of microAlgo and Algo and safely convert between them.
 
 Any AlgoKit Utils function that needs an Algo amount will take an `AlgoAmount` object, which ensures that there is never any confusion about what value is being passed around. You can safely and explicitly convert to microAlgo or Algo when needed.
diff --git a/docs/src/content/docs/concepts/core/client.md b/docs/src/content/docs/concepts/core/client.md
@@ -1,10 +1,8 @@
 ---
 title: "Client management"
-description: "Client management is one of the core capabilities provided by AlgoKit Utils. It allows you to create (auto-retry) [algod](https://dev.algorand.co/reference/rest-apis/algod), [indexer](https://dev.algo..."
+description: "Client management is one of the core capabilities provided by AlgoKit Utils. It allows you to create (auto-retry) [algod](https://dev.algorand.co/reference/rest-apis/algod), [indexer](https://dev.algorand.co/reference/rest-apis/indexer) and [kmd](https://dev.algorand.co/reference/rest-apis/kmd) clients against various networks resolved from environment or specified configuration."
 ---
 
-# Client management
-
 Client management is one of the core capabilities provided by AlgoKit Utils. It allows you to create (auto-retry) [algod](https://dev.algorand.co/reference/rest-apis/algod), [indexer](https://dev.algorand.co/reference/rest-apis/indexer) and [kmd](https://dev.algorand.co/reference/rest-apis/kmd) clients against various networks resolved from environment or specified configuration.
 
 > [!TIP]
diff --git a/docs/src/content/docs/concepts/core/transaction.md b/docs/src/content/docs/concepts/core/transaction.md
@@ -1,10 +1,8 @@
 ---
 title: "Transaction management"
-description: "Transaction management is one of the core capabilities provided by AlgoKit Utils. It allows you to construct, simulate and send single, or grouped transactions with consistent and highly configurable ..."
+description: "Transaction management is one of the core capabilities provided by AlgoKit Utils. It allows you to construct, simulate and send single, or grouped transactions with consistent and highly configurable semantics, including configurable control of transaction notes, logging, fees, multiple sender account types, and sending behaviour."
 ---
 
-# Transaction management
-
 Transaction management is one of the core capabilities provided by AlgoKit Utils. It allows you to construct, simulate and send single, or grouped transactions with consistent and highly configurable semantics, including configurable control of transaction notes, logging, fees, multiple sender account types, and sending behaviour.
 
 > [!TIP]
diff --git a/docs/src/content/docs/migration/v7-migration.md b/docs/src/content/docs/migration/v7-migration.md
diff --git a/docs/src/content/docs/migration/v8-migration.md b/docs/src/content/docs/migration/v8-migration.md
diff --git a/docs/src/content/docs/migration/v9-to-v10-migration.md b/docs/src/content/docs/migration/v9-to-v10-migration.md
diff --git a/docs/src/content/docs/tutorials/README.md b/docs/src/content/docs/tutorials/README.md
diff --git a/docs/src/content/docs/tutorials/quick-start.md b/docs/src/content/docs/tutorials/quick-start.md
