Skip to content

Conversation

@critesjosh
Copy link
Contributor

@critesjosh critesjosh commented Jan 8, 2026

Summary

  • Adds references frontmatter to 28 documentation files that include code snippets via #include_code macros
  • Creates helper script docs/scripts/extract_references.sh to extract references from documentation files
  • Updates check_doc_references.sh to support directory references with /* suffix
  • Updates docs/README.md with documentation about the references format
  • Updates docs/CLAUDE.md with reminder about updating docs when changing processes
  • Enables automatic DevRel review notifications when referenced source files change in PRs

Files Updated

Category Count Files
Contract Tutorials 2 counter_contract.md, token_contract.md
JS Tutorials 2 aztecjs-getting-started.md, token_bridge.md
Framework Documentation 18 Various aztec-nr/ files
Foundational Topics 6 transactions.md, state_management.md, wallets.md, fees.md, call_types.md, keys.md

How It Works

Documentation files can now declare source code dependencies via frontmatter:

---
title: Counter Contract
references: ["docs/examples/contracts/counter_contract/src/main.nr"]
---

Directory references use /* suffix to indicate all files within that directory:

references: ["noir-projects/aztec-nr/aztec/src/context/*"]

When any file within that directory changes, the documentation will be flagged for review.

When referenced paths change in a PR, docs/scripts/check_doc_references.sh:

  1. Requests @AztecProtocol/devrel as reviewers
  2. Posts a PR comment listing affected documentation

Reference Format

  • Individual files: "path/to/file.ts"
  • Directories (all files within): "path/to/directory/*"

Test Plan

  • All 28 documentation files have references frontmatter
  • All referenced paths (files and directories) verified to exist
  • Script logic tested for both file and directory matching
  • Documentation updated in README.md and CLAUDE.md

🤖 Generated with Claude Code

@critesjosh critesjosh changed the title docs: add references frontmatter to documentation files fix(docs): add references frontmatter to documentation files Jan 8, 2026
@critesjosh critesjosh requested a review from sklppy88 January 8, 2026 21:54
@critesjosh critesjosh force-pushed the jc/expand-doc-references branch 3 times, most recently from 162af73 to 0eafd85 Compare January 9, 2026 14:50
Add `references` frontmatter to 28 documentation files that include code
snippets via `#include_code` macros. This enables automatic notifications
when referenced source files change in PRs.

Changes:
- Add references to 28 doc files (tutorials, framework docs, foundational topics)
- Create helper script `docs/scripts/extract_references.sh`
- Update `check_doc_references.sh` to support directory references with /* suffix
- Update README.md with documentation about references format
- Update CLAUDE.md with reminder about updating docs when changing processes

Directory references use /* suffix (e.g., "path/to/dir/*") to indicate all
files within that directory should trigger review notifications.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@critesjosh critesjosh force-pushed the jc/expand-doc-references branch from 0eafd85 to f62815e Compare January 9, 2026 15:15
Copy link
Contributor

@sklppy88 sklppy88 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i like auto including the include codes, although now im thinking a possible further improvement is have the frontmatter references able to reference specific lines (kind of like how include code does it). just a thing to flag and think about later

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants