feat(docs): improve discoverability of Aztec.nr API reference docs#22861
Merged
critesjosh merged 8 commits intonextfrom May 4, 2026
Merged
Conversation
Add static API docs to sitemap, Typesense search index, and LLM context files so they are findable via search engines, site search, and AI tools.
Extracted into #22647 so the doc corrections can land independently.
…or improved API discoverability
- Strip trailing slash from SITE_URL to avoid double slashes in sitemap entries - Sort markdown API files and cap llms.txt link list at 100 entries - Skip llms.txt updates when no API docs are found on disk - Tune Typesense page_rank and text selectors for Aztec.nr API
alejoamiras
approved these changes
May 3, 2026
critesjosh
deleted the
josh/ecodr-877-improve-discoverability-of-aztecnr-api-docs
branch
Collaborator
|
❌ Failed to cherry-pick to |
4 tasks
critesjosh
added a commit
that referenced
this pull request
May 4, 2026
…e docs (#22861) to v4-next (#22931) Backport of #22861 to v4-next. ## Summary Improves discoverability of the Aztec.nr API reference docs through search, sitemap, and `llms.txt` enhancements: - Adds `docs/scripts/augment_sitemap.js` — a post-build script that appends entries for the auto-generated API docs (`static/aztec-nr-api/<type>/...`) to `sitemap.xml` so they get indexed. - Tunes `docs/typesense.config.json`: `page_rank`-weighted `start_urls`, an `api-nr` selector profile for HTML API pages, and `stop_urls` to skip Noir stdlib / `all.html` / per-constant globals. - Cleans up `docs/scripts/append_api_docs_to_llms.js`: deterministic markdown sort, 100-link cap per section, skip-if-empty behavior, and `format` field to drive HTML vs markdown handling. Also adds a TypeScript API Reference entry alongside the Aztec.nr one. - Wires `node scripts/augment_sitemap.js` into the `build` script in `docs/package.json`. ## Conflict resolution The cherry-pick of merge commit `77db5987` conflicted in `docs/scripts/append_api_docs_to_llms.js`. The PR was authored on top of an earlier commit on `next` that introduced `developerVersionConfig` / `defaultType` / `defaultVersion` machinery, which is not yet on v4-next — v4-next still derived the API directory list from `testnetVersion` only. Resolution: adopted the new `developerVersionConfig` model, since: 1. `docs/developer_version_config.json` already exists on v4-next (`mainnet: v4.2.0-aztecnr-rc.2`, `testnet: v4.1.0-rc.2`). 2. The newly added `docs/scripts/augment_sitemap.js` also reads `developer_version_config.json` and uses the same `defaultType` priority logic, so adopting the new model keeps the two scripts consistent. After resolution, `docs/scripts/append_api_docs_to_llms.js` matches the merged PR exactly. ## Commit structure 1. `feat(docs): improve discoverability ... (#22861)` — original cherry-pick with conflict markers preserved as-is (does not run on its own). 2. `fix: resolve cherry-pick conflicts in append_api_docs_to_llms.js` — replaces the conflicted region with the merged result. No separate build-fix commit was needed: smoke-tested both scripts with empty and populated `static/aztec-nr-api/<type>` and `typescript-api/<type>` trees and they produce the expected `llms.txt`, `llms-full.txt`, and `sitemap.xml` augmentations. ## Test plan - [ ] `yarn build` in `docs/` completes without errors - [ ] Generated `sitemap.xml` includes API reference URLs with no double slashes - [ ] `llms.txt` and `llms-full.txt` contain API Reference sections in stable order, capped at 100 links per section - [ ] Typesense search surfaces Aztec.nr API entries with reasonable ranking ClaudeBox log: https://claudebox.work/s/c691d7afed6323c2?run=1
AztecBot
added a commit
that referenced
this pull request
May 5, 2026
BEGIN_COMMIT_OVERRIDE docs: add map and state variable docs (#22824) fix: e2e compat should not fail for contracts added after legacy stables (#22900) chore: fix kv-store browser tests hangs (#22721) feat: kv-store sqlite backend with page level encryption (#22759) fix: install node 22 for aztec-cli acceptance test (#22917) feat: backport kv-store sqlite encryption (#22759) to v4-next (#22927) fix(docs): correct llms.txt links for versioned developer docs (#22819) feat(docs): improve discoverability of Aztec.nr API reference docs (#22861) feat(docs): backport improve discoverability of Aztec.nr API reference docs (#22861) to v4-next (#22931) feat(aztec-nr): add call_self stubs for utility functions (#22885) docs: add map and state variable docs (backport #22824) (#22880) refactor: `getPackageVersion` fn cleanup (#22941) fix(ci): skip acceptance test for canary -commit. tags (#22951) fix: closing db, correct stub side effects (#22939) END_COMMIT_OVERRIDE
This was referenced May 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Improves discoverability of the Aztec.nr API reference docs through search, sitemap, and
llms.txtenhancements.page_rank, text selectors) to surface Aztec.nr API content in docs search.llms.txt/llms-full.txtgeneration: sorts markdown files deterministically, caps the link list at 100 entries, skips updates when no API docs are present on disk, and strips trailing slashes fromSITE_URL.Linear: ECODR-877
Test plan
yarn buildindocs/completes without errorssitemap.xmlincludes API reference URLs with no double slashesllms.txtandllms-full.txtcontain API Reference sections in stable order, capped at 100 links per section