Skip to content

Commit 45f88a8

Browse files
critesjoshcritesjosh
authored
fix(docs): simplify TypeScript API reference links (#22232)
## Summary - Remove dynamic version resolution components (`ApiLink`, `ApiFile`, `ApiPath`, `useApiVersion`) from `typescript_api_reference.mdx` in favor of static `pathname:///` links that work correctly with the preprocessor - Update validation script to skip unresolved preprocessor macros (e.g., `#api_ref_version` in source files) - Applied across source docs and versioned copies (v4.1.0-rc.2, v4.2.0-aztecnr-rc.2) ## Test plan - [ ] `yarn build` in docs/ succeeds - [ ] TypeScript API reference page renders correctly with working links - [ ] Validation script passes without false positives on preprocessor macros
2 parents dddbaab + 6123032 commit 45f88a8

File tree

4 files changed

+51
-174
lines changed

4 files changed

+51
-174
lines changed

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

Lines changed: 15 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -3,45 +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-
const label = version.label || "";
13-
if (label.startsWith("Alpha")) return "mainnet";
14-
if (label.startsWith("Testnet")) return "testnet";
15-
if (label.startsWith("Devnet")) return "devnet";
16-
if (label.includes("nightly")) return "nightly";
17-
return version.name;
18-
};
19-
20-
export const ApiLink = ({ path, children }) => {
21-
const apiVersion = useApiVersion();
22-
const href = `/typescript-api/${apiVersion}/${path}`;
23-
return (
24-
<a href={href} target="_blank" rel="noopener noreferrer">
25-
{children}
26-
</a>
27-
);
28-
};
29-
30-
export const ApiPath = () => {
31-
const apiVersion = useApiVersion();
32-
return <code>/typescript-api/{apiVersion}/</code>;
33-
};
34-
35-
export const CopyIcon = ({ path, absolute = false }) => {
36-
const apiVersion = useApiVersion();
8+
export const CopyIcon = ({ path }) => {
379
const [status, setStatus] = useState("idle");
3810

3911
const handleCopy = async (e) => {
4012
e.preventDefault();
41-
const url = absolute ? path : `/typescript-api/${apiVersion}/${path}`;
4213
setStatus("loading");
4314
try {
44-
const response = await fetch(url);
15+
const response = await fetch(path);
4516
if (!response.ok) throw new Error("Failed to fetch");
4617
const text = await response.text();
4718
await navigator.clipboard.writeText(text);
@@ -104,19 +75,6 @@ export const CopyIcon = ({ path, absolute = false }) => {
10475
);
10576
};
10677

107-
export const ApiFile = ({ path, children }) => {
108-
const apiVersion = useApiVersion();
109-
const href = `/typescript-api/${apiVersion}/${path}`;
110-
return (
111-
<span style={{ whiteSpace: "nowrap" }}>
112-
<a href={href} target="_blank" rel="noopener noreferrer">
113-
<code>{children || path}</code>
114-
</a>
115-
<CopyIcon path={path} />
116-
</span>
117-
);
118-
};
119-
12078
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.
12179

12280
## Package Categories
@@ -152,25 +110,25 @@ Common types like `Fr`, `AztecAddress`, and `EthAddress` are re-exported through
152110

153111
For LLM consumption, we provide machine-readable documentation in multiple formats:
154112

155-
- **[llms.txt](pathname:///llms.txt)** <CopyIcon path="/llms.txt" absolute={true} /> - Full documentation optimized for LLM context
156-
- <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
157115

158116
### Markdown API Files
159117

160-
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/`:
161119

162120
| File | Description |
163121
| --------------------------------------- | ----------------------------------------------- |
164-
| <ApiFile path="llm-summary.txt" /> | Human-readable summary with package overview |
165-
| <ApiFile path="aztec.js.md" /> | Main SDK - contracts, transactions, accounts |
166-
| <ApiFile path="accounts.md" /> | Account implementations (ECDSA, Schnorr) |
167-
| <ApiFile path="pxe.md" /> | Private execution environment client |
168-
| <ApiFile path="wallet-sdk.md" /> | Browser/extension wallet integration |
169-
| <ApiFile path="entrypoints.md" /> | Transaction entrypoints for account abstraction |
170-
| <ApiFile path="stdlib.md" /> | Protocol types (transactions, blocks, proofs) |
171-
| <ApiFile path="foundation.md" /> | Low-level utilities (crypto, serialization) |
172-
| <ApiFile path="wallets.md" /> | Embedded wallet for browser and Node.js |
173-
| <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 |
174132

175133
## Related Resources
176134

‎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 & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -3,45 +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-
return version.name;
18-
};
19-
20-
export const ApiLink = ({ path, children }) => {
21-
const apiVersion = useApiVersion();
22-
const href = `/typescript-api/${apiVersion}/${path}`;
23-
return (
24-
<a href={href} target="_blank" rel="noopener noreferrer">
25-
{children}
26-
</a>
27-
);
28-
};
29-
30-
export const ApiPath = () => {
31-
const apiVersion = useApiVersion();
32-
return <code>/typescript-api/{apiVersion}/</code>;
33-
};
34-
35-
export const CopyIcon = ({ path, absolute = false }) => {
36-
const apiVersion = useApiVersion();
8+
export const CopyIcon = ({ path }) => {
379
const [status, setStatus] = useState("idle");
3810

3911
const handleCopy = async (e) => {
4012
e.preventDefault();
41-
const url = absolute ? path : `/typescript-api/${apiVersion}/${path}`;
4213
setStatus("loading");
4314
try {
44-
const response = await fetch(url);
15+
const response = await fetch(path);
4516
if (!response.ok) throw new Error("Failed to fetch");
4617
const text = await response.text();
4718
await navigator.clipboard.writeText(text);
@@ -104,19 +75,6 @@ export const CopyIcon = ({ path, absolute = false }) => {
10475
);
10576
};
10677

107-
export const ApiFile = ({ path, children }) => {
108-
const apiVersion = useApiVersion();
109-
const href = `/typescript-api/${apiVersion}/${path}`;
110-
return (
111-
<span style={{ whiteSpace: "nowrap" }}>
112-
<a href={href} target="_blank" rel="noopener noreferrer">
113-
<code>{children || path}</code>
114-
</a>
115-
<CopyIcon path={path} />
116-
</span>
117-
);
118-
};
119-
12078
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.
12179

12280
## Package Categories
@@ -152,25 +110,25 @@ Common types like `Fr`, `AztecAddress`, and `EthAddress` are re-exported through
152110

153111
For LLM consumption, we provide machine-readable documentation in multiple formats:
154112

155-
- **[llms.txt](pathname:///llms.txt)** <CopyIcon path="/llms.txt" absolute={true} /> - Full documentation optimized for LLM context
156-
- <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
157115

158116
### Markdown API Files
159117

160-
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/`:
161119

162120
| File | Description |
163121
| --------------------------------------- | ----------------------------------------------- |
164-
| <ApiFile path="llm-summary.txt" /> | Human-readable summary with package overview |
165-
| <ApiFile path="aztec.js.md" /> | Main SDK - contracts, transactions, accounts |
166-
| <ApiFile path="accounts.md" /> | Account implementations (ECDSA, Schnorr) |
167-
| <ApiFile path="pxe.md" /> | Private execution environment client |
168-
| <ApiFile path="wallet-sdk.md" /> | Browser/extension wallet integration |
169-
| <ApiFile path="wallets.md" /> | Embedded wallet for browser and Node.js |
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="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 |
174132

175133
## Related Resources
176134

‎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)