Skip to content

Commit 920b7a1

Browse files
critesjoshcritesjosh
authored
fix(docs): simplify TypeScript API reference links (backport #22232) (#22369)
## Summary Backport of #22232 to v4-next. - Removes dynamic version resolution components (`ApiLink`, `ApiFile`, `ApiPath`, `useApiVersion`) from `typescript_api_reference.mdx` in favor of static `pathname:///` links - Simplifies `CopyIcon` component to take direct paths instead of computing them from API version - Updates validation script to skip unresolved preprocessor macros ## Cherry-pick conflicts Conflicts occurred in both `typescript_api_reference.mdx` files (source and v4.1.0-rc.2 versioned copy) because the v4-next branch had slightly different `useApiVersion` implementations. Resolved by taking the incoming simplified `CopyIcon` component and removing all dynamic version components, matching the PR's intent. ## Commit structure 1. **Cherry-pick with conflicts** — original cherry-pick attempt with conflict markers preserved 2. **Conflict resolution** — resolved by accepting the simplified component definitions ClaudeBox log: https://claudebox.work/s/363a65f4781acd9e?run=1
2 parents d4963bf + b7a504b commit 920b7a1

5 files changed

Lines changed: 53 additions & 175 deletions

File tree

‎docs/developer_versioned_docs/version-v4.1.0-rc.2/docs/aztec-js/typescript_api_reference.mdx‎

Lines changed: 15 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -3,46 +3,16 @@ title: TypeScript API Reference
33
description: API reference documentation for Aztec TypeScript packages including aztec.js, accounts, PXE, and core libraries.
44
---
55

6-
import { useActiveVersion } from "@docusaurus/plugin-content-docs/client";
76
import { useState } from "react";
87

9-
export const useApiVersion = () => {
10-
const version = useActiveVersion("developer");
11-
const versionName = version?.name || "current";
12-
// Map Docusaurus version to API docs folder
13-
// Use stable paths for nightly/devnet, version-specific for others
14-
if (versionName === "current") return "next";
15-
if (versionName.includes("nightly")) return "nightly";
16-
if (versionName.includes("devnet")) return "devnet";
17-
if (versionName.includes("rc") || versionName.includes("testnet")) return "testnet";
18-
return versionName;
19-
};
20-
21-
export const ApiLink = ({ path, children }) => {
22-
const apiVersion = useApiVersion();
23-
const href = `/typescript-api/${apiVersion}/${path}`;
24-
return (
25-
<a href={href} target="_blank" rel="noopener noreferrer">
26-
{children}
27-
</a>
28-
);
29-
};
30-
31-
export const ApiPath = () => {
32-
const apiVersion = useApiVersion();
33-
return <code>/typescript-api/{apiVersion}/</code>;
34-
};
35-
36-
export const CopyIcon = ({ path, absolute = false }) => {
37-
const apiVersion = useApiVersion();
8+
export const CopyIcon = ({ path }) => {
389
const [status, setStatus] = useState("idle");
3910

4011
const handleCopy = async (e) => {
4112
e.preventDefault();
42-
const url = absolute ? path : `/typescript-api/${apiVersion}/${path}`;
4313
setStatus("loading");
4414
try {
45-
const response = await fetch(url);
15+
const response = await fetch(path);
4616
if (!response.ok) throw new Error("Failed to fetch");
4717
const text = await response.text();
4818
await navigator.clipboard.writeText(text);
@@ -105,19 +75,6 @@ export const CopyIcon = ({ path, absolute = false }) => {
10575
);
10676
};
10777

108-
export const ApiFile = ({ path, children }) => {
109-
const apiVersion = useApiVersion();
110-
const href = `/typescript-api/${apiVersion}/${path}`;
111-
return (
112-
<span style={{ whiteSpace: "nowrap" }}>
113-
<a href={href} target="_blank" rel="noopener noreferrer">
114-
<code>{children || path}</code>
115-
</a>
116-
<CopyIcon path={path} />
117-
</span>
118-
);
119-
};
120-
12178
This section provides API reference documentation for the Aztec TypeScript packages. These packages enable developers to build applications on Aztec, from simple contract interactions to complex privacy-preserving protocols.
12279

12380
## Package Categories
@@ -153,25 +110,25 @@ Common types like `Fr`, `AztecAddress`, and `EthAddress` are re-exported through
153110

154111
For LLM consumption, we provide machine-readable documentation in multiple formats:
155112

156-
- **[llms.txt](pathname:///llms.txt)** <CopyIcon path="/llms.txt" absolute={true} /> - Full documentation optimized for LLM context
157-
- <ApiLink path="llm-summary.txt">**LLM Summary**</ApiLink> <CopyIcon path="llm-summary.txt" /> - Human-readable API summary
113+
- **[llms.txt](pathname:///llms.txt)** <CopyIcon path="/llms.txt" /> - Full documentation optimized for LLM context
114+
- [**LLM Summary**](pathname:///typescript-api/testnet/llm-summary.txt) <CopyIcon path="/typescript-api/testnet/llm-summary.txt" /> - Human-readable API summary
158115

159116
### Markdown API Files
160117

161-
The following markdown files are available for LLM context inclusion at <ApiPath />:
118+
The following markdown files are available for LLM context inclusion at `/typescript-api/testnet/`:
162119

163120
| File | Description |
164121
| --------------------------------------- | ----------------------------------------------- |
165-
| <ApiFile path="llm-summary.txt" /> | Human-readable summary with package overview |
166-
| <ApiFile path="aztec.js.md" /> | Main SDK - contracts, transactions, accounts |
167-
| <ApiFile path="accounts.md" /> | Account implementations (ECDSA, Schnorr) |
168-
| <ApiFile path="pxe.md" /> | Private execution environment client |
169-
| <ApiFile path="wallet-sdk.md" /> | Browser/extension wallet integration |
170-
| <ApiFile path="entrypoints.md" /> | Transaction entrypoints for account abstraction |
171-
| <ApiFile path="stdlib.md" /> | Protocol types (transactions, blocks, proofs) |
172-
| <ApiFile path="foundation.md" /> | Low-level utilities (crypto, serialization) |
173-
| <ApiFile path="wallets.md" /> | Embedded wallet for browser and Node.js |
174-
| <ApiFile path="constants.md" /> | Protocol constants for circuits |
122+
| [`llm-summary.txt`](pathname:///typescript-api/testnet/llm-summary.txt) <CopyIcon path="/typescript-api/testnet/llm-summary.txt" /> | Human-readable summary with package overview |
123+
| [`aztec.js.md`](pathname:///typescript-api/testnet/aztec.js.md) <CopyIcon path="/typescript-api/testnet/aztec.js.md" /> | Main SDK - contracts, transactions, accounts |
124+
| [`accounts.md`](pathname:///typescript-api/testnet/accounts.md) <CopyIcon path="/typescript-api/testnet/accounts.md" /> | Account implementations (ECDSA, Schnorr) |
125+
| [`pxe.md`](pathname:///typescript-api/testnet/pxe.md) <CopyIcon path="/typescript-api/testnet/pxe.md" /> | Private execution environment client |
126+
| [`wallet-sdk.md`](pathname:///typescript-api/testnet/wallet-sdk.md) <CopyIcon path="/typescript-api/testnet/wallet-sdk.md" /> | Browser/extension wallet integration |
127+
| [`entrypoints.md`](pathname:///typescript-api/testnet/entrypoints.md) <CopyIcon path="/typescript-api/testnet/entrypoints.md" /> | Transaction entrypoints for account abstraction |
128+
| [`stdlib.md`](pathname:///typescript-api/testnet/stdlib.md) <CopyIcon path="/typescript-api/testnet/stdlib.md" /> | Protocol types (transactions, blocks, proofs) |
129+
| [`foundation.md`](pathname:///typescript-api/testnet/foundation.md) <CopyIcon path="/typescript-api/testnet/foundation.md" /> | Low-level utilities (crypto, serialization) |
130+
| [`wallets.md`](pathname:///typescript-api/testnet/wallets.md) <CopyIcon path="/typescript-api/testnet/wallets.md" /> | Embedded wallet for browser and Node.js |
131+
| [`constants.md`](pathname:///typescript-api/testnet/constants.md) <CopyIcon path="/typescript-api/testnet/constants.md" /> | Protocol constants for circuits |
175132

176133
## Related Resources
177134

‎docs/developer_versioned_docs/version-v4.2.0-aztecnr-rc.2/docs/aztec-js/typescript_api_reference.mdx‎

Lines changed: 15 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -3,47 +3,16 @@ title: TypeScript API Reference
33
description: API reference documentation for Aztec TypeScript packages including aztec.js, accounts, PXE, and core libraries.
44
---
55

6-
import { useActiveVersion } from "@docusaurus/plugin-content-docs/client";
76
import { useState } from "react";
87

9-
export const useApiVersion = () => {
10-
const version = useActiveVersion("developer");
11-
if (!version || version.name === "current") return "next";
12-
// Map Docusaurus version to API docs folder using version label
13-
// Labels are set explicitly in docusaurus.config.js (e.g., "Mainnet (...)")
14-
const label = version.label || "";
15-
if (label.startsWith("Alpha")) return "mainnet";
16-
if (label.startsWith("Testnet")) return "testnet";
17-
if (label.startsWith("Devnet")) return "devnet";
18-
if (label.includes("nightly")) return "nightly";
19-
return version.name;
20-
};
21-
22-
export const ApiLink = ({ path, children }) => {
23-
const apiVersion = useApiVersion();
24-
const href = `/typescript-api/${apiVersion}/${path}`;
25-
return (
26-
<a href={href} target="_blank" rel="noopener noreferrer">
27-
{children}
28-
</a>
29-
);
30-
};
31-
32-
export const ApiPath = () => {
33-
const apiVersion = useApiVersion();
34-
return <code>/typescript-api/{apiVersion}/</code>;
35-
};
36-
37-
export const CopyIcon = ({ path, absolute = false }) => {
38-
const apiVersion = useApiVersion();
8+
export const CopyIcon = ({ path }) => {
399
const [status, setStatus] = useState("idle");
4010

4111
const handleCopy = async (e) => {
4212
e.preventDefault();
43-
const url = absolute ? path : `/typescript-api/${apiVersion}/${path}`;
4413
setStatus("loading");
4514
try {
46-
const response = await fetch(url);
15+
const response = await fetch(path);
4716
if (!response.ok) throw new Error("Failed to fetch");
4817
const text = await response.text();
4918
await navigator.clipboard.writeText(text);
@@ -106,19 +75,6 @@ export const CopyIcon = ({ path, absolute = false }) => {
10675
);
10776
};
10877

109-
export const ApiFile = ({ path, children }) => {
110-
const apiVersion = useApiVersion();
111-
const href = `/typescript-api/${apiVersion}/${path}`;
112-
return (
113-
<span style={{ whiteSpace: "nowrap" }}>
114-
<a href={href} target="_blank" rel="noopener noreferrer">
115-
<code>{children || path}</code>
116-
</a>
117-
<CopyIcon path={path} />
118-
</span>
119-
);
120-
};
121-
12278
This section provides API reference documentation for the Aztec TypeScript packages. These packages enable developers to build applications on Aztec, from simple contract interactions to complex privacy-preserving protocols.
12379

12480
## Package Categories
@@ -154,25 +110,25 @@ Common types like `Fr`, `AztecAddress`, and `EthAddress` are re-exported through
154110

155111
For LLM consumption, we provide machine-readable documentation in multiple formats:
156112

157-
- **[llms.txt](pathname:///llms.txt)** <CopyIcon path="/llms.txt" absolute={true} /> - Full documentation optimized for LLM context
158-
- <ApiLink path="llm-summary.txt">**LLM Summary**</ApiLink> <CopyIcon path="llm-summary.txt" /> - Human-readable API summary
113+
- **[llms.txt](pathname:///llms.txt)** <CopyIcon path="/llms.txt" /> - Full documentation optimized for LLM context
114+
- [**LLM Summary**](pathname:///typescript-api/mainnet/llm-summary.txt) <CopyIcon path="/typescript-api/mainnet/llm-summary.txt" /> - Human-readable API summary
159115

160116
### Markdown API Files
161117

162-
The following markdown files are available for LLM context inclusion at <ApiPath />:
118+
The following markdown files are available for LLM context inclusion at `/typescript-api/mainnet/`:
163119

164120
| File | Description |
165121
| --------------------------------------- | ----------------------------------------------- |
166-
| <ApiFile path="llm-summary.txt" /> | Human-readable summary with package overview |
167-
| <ApiFile path="aztec.js.md" /> | Main SDK - contracts, transactions, accounts |
168-
| <ApiFile path="accounts.md" /> | Account implementations (ECDSA, Schnorr) |
169-
| <ApiFile path="pxe.md" /> | Private execution environment client |
170-
| <ApiFile path="wallet-sdk.md" /> | Browser/extension wallet integration |
171-
| <ApiFile path="wallets.md" /> | Embedded wallet for browser and Node.js |
172-
| <ApiFile path="entrypoints.md" /> | Transaction entrypoints for account abstraction |
173-
| <ApiFile path="stdlib.md" /> | Protocol types (transactions, blocks, proofs) |
174-
| <ApiFile path="foundation.md" /> | Low-level utilities (crypto, serialization) |
175-
| <ApiFile path="constants.md" /> | Protocol constants for circuits |
122+
| [`llm-summary.txt`](pathname:///typescript-api/mainnet/llm-summary.txt) <CopyIcon path="/typescript-api/mainnet/llm-summary.txt" /> | Human-readable summary with package overview |
123+
| [`aztec.js.md`](pathname:///typescript-api/mainnet/aztec.js.md) <CopyIcon path="/typescript-api/mainnet/aztec.js.md" /> | Main SDK - contracts, transactions, accounts |
124+
| [`accounts.md`](pathname:///typescript-api/mainnet/accounts.md) <CopyIcon path="/typescript-api/mainnet/accounts.md" /> | Account implementations (ECDSA, Schnorr) |
125+
| [`pxe.md`](pathname:///typescript-api/mainnet/pxe.md) <CopyIcon path="/typescript-api/mainnet/pxe.md" /> | Private execution environment client |
126+
| [`wallet-sdk.md`](pathname:///typescript-api/mainnet/wallet-sdk.md) <CopyIcon path="/typescript-api/mainnet/wallet-sdk.md" /> | Browser/extension wallet integration |
127+
| [`wallets.md`](pathname:///typescript-api/mainnet/wallets.md) <CopyIcon path="/typescript-api/mainnet/wallets.md" /> | Embedded wallet for browser and Node.js |
128+
| [`entrypoints.md`](pathname:///typescript-api/mainnet/entrypoints.md) <CopyIcon path="/typescript-api/mainnet/entrypoints.md" /> | Transaction entrypoints for account abstraction |
129+
| [`stdlib.md`](pathname:///typescript-api/mainnet/stdlib.md) <CopyIcon path="/typescript-api/mainnet/stdlib.md" /> | Protocol types (transactions, blocks, proofs) |
130+
| [`foundation.md`](pathname:///typescript-api/mainnet/foundation.md) <CopyIcon path="/typescript-api/mainnet/foundation.md" /> | Low-level utilities (crypto, serialization) |
131+
| [`constants.md`](pathname:///typescript-api/mainnet/constants.md) <CopyIcon path="/typescript-api/mainnet/constants.md" /> | Protocol constants for circuits |
176132

177133
## Related Resources
178134

‎docs/docs-developers/docs/aztec-js/typescript_api_reference.mdx‎

Lines changed: 15 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -3,43 +3,16 @@ title: TypeScript API Reference
33
description: API reference documentation for Aztec TypeScript packages including aztec.js, accounts, PXE, and core libraries.
44
---
55

6-
import { useActiveVersion } from "@docusaurus/plugin-content-docs/client";
76
import { useState } from "react";
87

9-
export const useApiVersion = () => {
10-
const version = useActiveVersion("developer");
11-
const versionName = version?.name || "current";
12-
// Map Docusaurus version to API docs folder
13-
if (versionName === "current") return "next";
14-
if (versionName.includes("rc") || versionName.includes("testnet")) return "testnet";
15-
return versionName;
16-
};
17-
18-
export const ApiLink = ({ path, children }) => {
19-
const apiVersion = useApiVersion();
20-
const href = `/typescript-api/${apiVersion}/${path}`;
21-
return (
22-
<a href={href} target="_blank" rel="noopener noreferrer">
23-
{children}
24-
</a>
25-
);
26-
};
27-
28-
export const ApiPath = () => {
29-
const apiVersion = useApiVersion();
30-
return <code>/typescript-api/{apiVersion}/</code>;
31-
};
32-
33-
export const CopyIcon = ({ path, absolute = false }) => {
34-
const apiVersion = useApiVersion();
8+
export const CopyIcon = ({ path }) => {
359
const [status, setStatus] = useState("idle");
3610

3711
const handleCopy = async (e) => {
3812
e.preventDefault();
39-
const url = absolute ? path : `/typescript-api/${apiVersion}/${path}`;
4013
setStatus("loading");
4114
try {
42-
const response = await fetch(url);
15+
const response = await fetch(path);
4316
if (!response.ok) throw new Error("Failed to fetch");
4417
const text = await response.text();
4518
await navigator.clipboard.writeText(text);
@@ -102,19 +75,6 @@ export const CopyIcon = ({ path, absolute = false }) => {
10275
);
10376
};
10477

105-
export const ApiFile = ({ path, children }) => {
106-
const apiVersion = useApiVersion();
107-
const href = `/typescript-api/${apiVersion}/${path}`;
108-
return (
109-
<span style={{ whiteSpace: "nowrap" }}>
110-
<a href={href} target="_blank" rel="noopener noreferrer">
111-
<code>{children || path}</code>
112-
</a>
113-
<CopyIcon path={path} />
114-
</span>
115-
);
116-
};
117-
11878
This section provides API reference documentation for the Aztec TypeScript packages. These packages enable developers to build applications on Aztec, from simple contract interactions to complex privacy-preserving protocols.
11979

12080
## Package Categories
@@ -150,25 +110,25 @@ Common types like `Fr`, `AztecAddress`, and `EthAddress` are re-exported through
150110

151111
For LLM consumption, we provide machine-readable documentation in multiple formats:
152112

153-
- **[llms.txt](pathname:///llms.txt)** <CopyIcon path="/llms.txt" absolute={true} /> - Full documentation optimized for LLM context
154-
- <ApiLink path="llm-summary.txt">**LLM Summary**</ApiLink> <CopyIcon path="llm-summary.txt" /> - Human-readable API summary
113+
- **[llms.txt](pathname:///llms.txt)** <CopyIcon path="/llms.txt" /> - Full documentation optimized for LLM context
114+
- [**LLM Summary**](pathname:///typescript-api/#api_ref_version/llm-summary.txt) <CopyIcon path="/typescript-api/#api_ref_version/llm-summary.txt" /> - Human-readable API summary
155115

156116
### Markdown API Files
157117

158-
The following markdown files are available for LLM context inclusion at <ApiPath />:
118+
The following markdown files are available for LLM context inclusion at `/typescript-api/#api_ref_version/`:
159119

160120
| File | Description |
161121
| --------------------------------------- | ----------------------------------------------- |
162-
| <ApiFile path="llm-summary.txt" /> | Human-readable summary with package overview |
163-
| <ApiFile path="aztec.js.md" /> | Main SDK - contracts, transactions, accounts |
164-
| <ApiFile path="accounts.md" /> | Account implementations (ECDSA, Schnorr) |
165-
| <ApiFile path="pxe.md" /> | Private execution environment client |
166-
| <ApiFile path="wallet-sdk.md" /> | Browser/extension wallet integration |
167-
| <ApiFile path="wallets.md" /> | Embedded wallet for browser and Node.js |
168-
| <ApiFile path="entrypoints.md" /> | Transaction entrypoints for account abstraction |
169-
| <ApiFile path="stdlib.md" /> | Protocol types (transactions, blocks, proofs) |
170-
| <ApiFile path="foundation.md" /> | Low-level utilities (crypto, serialization) |
171-
| <ApiFile path="constants.md" /> | Protocol constants for circuits |
122+
| [`llm-summary.txt`](pathname:///typescript-api/#api_ref_version/llm-summary.txt) <CopyIcon path="/typescript-api/#api_ref_version/llm-summary.txt" /> | Human-readable summary with package overview |
123+
| [`aztec.js.md`](pathname:///typescript-api/#api_ref_version/aztec.js.md) <CopyIcon path="/typescript-api/#api_ref_version/aztec.js.md" /> | Main SDK - contracts, transactions, accounts |
124+
| [`accounts.md`](pathname:///typescript-api/#api_ref_version/accounts.md) <CopyIcon path="/typescript-api/#api_ref_version/accounts.md" /> | Account implementations (ECDSA, Schnorr) |
125+
| [`pxe.md`](pathname:///typescript-api/#api_ref_version/pxe.md) <CopyIcon path="/typescript-api/#api_ref_version/pxe.md" /> | Private execution environment client |
126+
| [`wallet-sdk.md`](pathname:///typescript-api/#api_ref_version/wallet-sdk.md) <CopyIcon path="/typescript-api/#api_ref_version/wallet-sdk.md" /> | Browser/extension wallet integration |
127+
| [`wallets.md`](pathname:///typescript-api/#api_ref_version/wallets.md) <CopyIcon path="/typescript-api/#api_ref_version/wallets.md" /> | Embedded wallet for browser and Node.js |
128+
| [`entrypoints.md`](pathname:///typescript-api/#api_ref_version/entrypoints.md) <CopyIcon path="/typescript-api/#api_ref_version/entrypoints.md" /> | Transaction entrypoints for account abstraction |
129+
| [`stdlib.md`](pathname:///typescript-api/#api_ref_version/stdlib.md) <CopyIcon path="/typescript-api/#api_ref_version/stdlib.md" /> | Protocol types (transactions, blocks, proofs) |
130+
| [`foundation.md`](pathname:///typescript-api/#api_ref_version/foundation.md) <CopyIcon path="/typescript-api/#api_ref_version/foundation.md" /> | Low-level utilities (crypto, serialization) |
131+
| [`constants.md`](pathname:///typescript-api/#api_ref_version/constants.md) <CopyIcon path="/typescript-api/#api_ref_version/constants.md" /> | Protocol constants for circuits |
172132

173133
## Related Resources
174134

‎docs/scripts/validate_api_ref_links.sh‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -413,7 +413,7 @@ get_expected_ts_api_version() {
413413
fi
414414
}
415415

416-
# Process a TypeScript API link found via ApiFile/ApiLink JSX props.
416+
# Process a TypeScript API link found via pathname:/// or JSX props.
417417
# These reference files under static/typescript-api/{version}/.
418418
# Args: $1 = source file, $2 = line number, $3 = file path (e.g., "wallets.md"),
419419
# $4 = expected TS API version
@@ -423,6 +423,11 @@ process_ts_api_link() {
423423
local file_path="$3"
424424
local expected_version="${4:-nightly}"
425425

426+
# Skip unresolved preprocessor macros (e.g., #api_ref_version in source files)
427+
if [[ "$expected_version" == *"#"* ]]; then
428+
return
429+
fi
430+
426431
TOTAL_COUNT=$((TOTAL_COUNT + 1))
427432

428433
local rel_source="${source_file#$DOCS_ROOT/}"

0 commit comments

Comments
 (0)