refactor: move contracts under Build > API, merge manuals into guides#121
Open
refactor: move contracts under Build > API, merge manuals into guides#121
Conversation
- Move docs/contracts/ to docs/build/api/contracts/ with Deployed
Addresses as the section index (skip vendor README)
- Merge docs/manuals/ into docs/guides/manuals/
- Remove Contracts and Manuals navbar links
- Remove contractsSidebar and manualsSidebar
- Update sync-contracts-docs.js output path and sidebar references
- Update homepage and supported-chains links
📝 WalkthroughWalkthroughThis PR restructures documentation by moving contracts-related docs from Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
docs/build/api/contracts/sdk/_category_.json (1)
1-10:⚠️ Potential issue | 🟡 MinorThis file will be overwritten by the sync script.
The sync script calls
cleanDir(DEST)which wipesdocs/build/api/contracts/before regenerating. Since the script'swriteCategorycall for CATEGORIES doesn't pass thekeyparameter (bug flagged insync-contracts-docs.js), the"key": "contracts-sdk"field will be lost on the next sync run.Either fix the script to pass
cat.key(as suggested), or this manual addition will need to be re-added after every sync.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/build/api/contracts/sdk/_category_.json` around lines 1 - 10, The generated category JSON is losing its "key" because the sync script's writeCategory call in sync-contracts-docs.js does not pass the category key; update the call that writes CATEGORIES (the writeCategory invocation) to include cat.key (or the equivalent property) so the generated object includes "key": "contracts-sdk" on regen, ensuring the writeCategory function receives and writes the key field for each category.scripts/sync-contracts-docs.js (1)
383-388:⚠️ Potential issue | 🟡 MinorThe
keyparameter is not passed when writing sub-category files.The
writeCategoryfunction was updated to accept an optionalkeyparameter (line 120), and the SDK category defineskey: 'contracts-sdk'(line 341). However, the loop writing sub-categories doesn't passcat.keytowriteCategory, so the key will never be written tosdk/_category_.jsonby this script.🔧 Proposed fix
for (const cat of CATEGORIES) { writeCategory(path.join(DEST, cat.dir), { label: cat.label, position: cat.position, + key: cat.key, }); }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@scripts/sync-contracts-docs.js` around lines 383 - 388, The loop that writes sub-category files calls writeCategory without forwarding the optional key, so CATEGORIES entries like the SDK item (key 'contracts-sdk') never get written; update the loop to pass cat.key into writeCategory (e.g., writeCategory(path.join(DEST, cat.dir), { label: cat.label, position: cat.position }, cat.key)) so the key is persisted into sdk/_category_.json and other sub-category files; keep using the existing writeCategory signature and handle undefined keys as before.docs/build/api/contracts/sdk/api-reference.md (1)
89-89:⚠️ Potential issue | 🟠 MajorBroken link: the referenced path does not exist.
The link
../operations/addresses.mdpoints to a non-existent path. Based on the PR restructure, the "Deployed Addresses" page is now atdocs/build/api/contracts/index.md. From this file's location (sdk/api-reference.md), the correct relative path should be../index.mdor use the doc ID directly.🔗 Proposed fix
-See [Deployed Addresses](../operations/addresses.md) for the full list. +See [Deployed Addresses](../index.md) for the full list.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/build/api/contracts/sdk/api-reference.md` at line 89, The Markdown link labeled "Deployed Addresses" currently points to a non-existent relative path "../operations/addresses.md"; update that link target in the sdk/api-reference.md file so it references the correct document (either change the target to "../index.md" relative to this file or replace it with the appropriate doc ID for the contracts index) so the "Deployed Addresses" link resolves correctly.
🧹 Nitpick comments (1)
scripts/sync-contracts-docs.js (1)
369-380: API category may conflict with manually committed file.The script writes
docs/build/api/_category_.jsonat runtime (lines 369-373), but there's also a manually committeddocs/build/api/_category_.jsonfile in this PR. Running the script will overwrite the manual file, though currently both have the same content. Consider either:
- Removing the manual file and relying solely on script generation, or
- Removing these lines from the script if manual control is preferred.
Having both creates a potential maintenance inconsistency.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@scripts/sync-contracts-docs.js` around lines 369 - 380, The script currently generates docs/build/api/_category_.json by calling writeCategory(API_CATEGORY.dir, ...) and also writes a Contracts category at DEST using writeCategory(DEST, ...), which will overwrite the manually committed docs/build/api/_category_.json in the repo; either remove the manual file from the repo and keep these writeCategory calls (recommended) or remove the two writeCategory calls (the write to API_CATEGORY.dir and the Contracts write to DEST) so the manual _category_.json remains authoritative—update whichever you choose and ensure API_CATEGORY and DEST usages are consistent with the chosen approach.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docusaurus.config.ts`:
- Line 95: Remove the orphaned client module file named hideContractsOn05x.js
from the repository since it is no longer referenced in clientModules; delete
the file from version control (git rm) and commit the removal so it no longer
appears in the codebase.
In `@src/pages/whitepaper.md`:
- Around line 302-310: In src/pages/whitepaper.md update the document link for
the table row referencing "[YELLOW MiCA White Paper v1.2 (PDF)]" so the href
points to the actual file location
"/static/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf" instead of
"/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf"; modify the table cell containing
the document link accordingly so the rendered link uses the /static/assets path.
---
Outside diff comments:
In `@docs/build/api/contracts/sdk/_category_.json`:
- Around line 1-10: The generated category JSON is losing its "key" because the
sync script's writeCategory call in sync-contracts-docs.js does not pass the
category key; update the call that writes CATEGORIES (the writeCategory
invocation) to include cat.key (or the equivalent property) so the generated
object includes "key": "contracts-sdk" on regen, ensuring the writeCategory
function receives and writes the key field for each category.
In `@docs/build/api/contracts/sdk/api-reference.md`:
- Line 89: The Markdown link labeled "Deployed Addresses" currently points to a
non-existent relative path "../operations/addresses.md"; update that link target
in the sdk/api-reference.md file so it references the correct document (either
change the target to "../index.md" relative to this file or replace it with the
appropriate doc ID for the contracts index) so the "Deployed Addresses" link
resolves correctly.
In `@scripts/sync-contracts-docs.js`:
- Around line 383-388: The loop that writes sub-category files calls
writeCategory without forwarding the optional key, so CATEGORIES entries like
the SDK item (key 'contracts-sdk') never get written; update the loop to pass
cat.key into writeCategory (e.g., writeCategory(path.join(DEST, cat.dir), {
label: cat.label, position: cat.position }, cat.key)) so the key is persisted
into sdk/_category_.json and other sub-category files; keep using the existing
writeCategory signature and handle undefined keys as before.
---
Nitpick comments:
In `@scripts/sync-contracts-docs.js`:
- Around line 369-380: The script currently generates
docs/build/api/_category_.json by calling writeCategory(API_CATEGORY.dir, ...)
and also writes a Contracts category at DEST using writeCategory(DEST, ...),
which will overwrite the manually committed docs/build/api/_category_.json in
the repo; either remove the manual file from the repo and keep these
writeCategory calls (recommended) or remove the two writeCategory calls (the
write to API_CATEGORY.dir and the Contracts write to DEST) so the manual
_category_.json remains authoritative—update whichever you choose and ensure
API_CATEGORY and DEST usages are consistent with the chosen approach.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: adf65378-9f40-48ea-8dfb-b4f8bafeace4
⛔ Files ignored due to path filters (1)
package-lock.jsonis excluded by!**/package-lock.json
📒 Files selected for processing (43)
docs/build/api/_category_.jsondocs/build/api/contracts/_category_.jsondocs/build/api/contracts/api-reference/_category_.jsondocs/build/api/contracts/api-reference/app-registry.mddocs/build/api/contracts/api-reference/faucet.mddocs/build/api/contracts/api-reference/interfaces/_category_.jsondocs/build/api/contracts/api-reference/interfaces/ilock.mddocs/build/api/contracts/api-reference/interfaces/islash.mddocs/build/api/contracts/api-reference/locker.mddocs/build/api/contracts/api-reference/node-registry.mddocs/build/api/contracts/api-reference/treasury.mddocs/build/api/contracts/api-reference/yellow-governor.mddocs/build/api/contracts/api-reference/yellow-token.mddocs/build/api/contracts/faq.mddocs/build/api/contracts/index.mddocs/build/api/contracts/integration/_category_.jsondocs/build/api/contracts/integration/deployment.mddocs/build/api/contracts/integration/events.mddocs/build/api/contracts/integration/ui-spec.mddocs/build/api/contracts/protocol/_category_.jsondocs/build/api/contracts/protocol/governance.mddocs/build/api/contracts/protocol/overview.mddocs/build/api/contracts/protocol/slashing.mddocs/build/api/contracts/protocol/staking.mddocs/build/api/contracts/protocol/treasury.mddocs/build/api/contracts/sdk/_category_.jsondocs/build/api/contracts/sdk/api-reference.mddocs/build/api/contracts/sdk/examples.mddocs/build/api/contracts/sdk/getting-started.mddocs/contracts/index.mddocs/guides/index.mddocs/guides/manuals/_category_.jsondocs/guides/manuals/request-asset-support.mddocs/guides/manuals/request-blockchain-support.mddocs/guides/manuals/running-clearnode-locally.mddocs/learn/introduction/supported-chains.mdxdocs/manuals/_category_.jsondocs/manuals/index.mddocusaurus.config.tsscripts/sync-contracts-docs.jssidebars.tssrc/components/HomepageFeatures/index.tsxsrc/pages/whitepaper.md
💤 Files with no reviewable changes (4)
- sidebars.ts
- docs/contracts/index.md
- docs/manuals/index.md
- docs/manuals/category.json
| clientModules: [ | ||
| './src/clientModules/hideContractsOn05x.js', | ||
| ], | ||
| clientModules: [], |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check if hideContractsOn05x.js still exists in the repository
fd -t f "hideContractsOn05x.js"Repository: layer-3/docs
Length of output: 95
Delete the orphaned client module file.
The file src/clientModules/hideContractsOn05x.js still exists in the repository but is no longer referenced in clientModules. This dead code should be deleted.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docusaurus.config.ts` at line 95, Remove the orphaned client module file
named hideContractsOn05x.js from the repository since it is no longer referenced
in clientModules; delete the file from version control (git rm) and commit the
removal so it no longer appears in the codebase.
src/pages/whitepaper.md
Outdated
Comment on lines
+302
to
+310
| --- | ||
|
|
||
| ## MiCA White Paper Filing History | ||
|
|
||
| The following versions of the YELLOW crypto-asset white paper have been filed under the Markets in Crypto-Assets Regulation (EU) 2023/1114: | ||
|
|
||
| | Version | Date of Notification | Status | Document | | ||
| |---|---|---|---| | ||
| | v1.2 | 2025-11-14 | Current | [YELLOW MiCA White Paper v1.2 (PDF)](/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf) | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Check if the referenced PDF file exists
# Check for the PDF file in the assets directory
if [ -f "assets/YELLOW_MiCA_White_Paper_v.1.2.pdf" ]; then
echo "✓ PDF file exists at assets/YELLOW_MiCA_White_Paper_v.1.2.pdf"
ls -lh "assets/YELLOW_MiCA_White_Paper_v.1.2.pdf"
else
echo "✗ PDF file not found at assets/YELLOW_MiCA_White_Paper_v.1.2.pdf"
echo "Searching for similar files..."
fd -e pdf -i mica . 2>/dev/null || echo "No similar PDF files found"
fiRepository: layer-3/docs
Length of output: 201
Update the PDF reference path to match the actual file location.
The PDF file exists at /static/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf, not at the referenced path /assets/YELLOW_MiCA_White_Paper_v.1.2.pdf. Update the link on line 307 to the correct location.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/pages/whitepaper.md` around lines 302 - 310, In src/pages/whitepaper.md
update the document link for the table row referencing "[YELLOW MiCA White Paper
v1.2 (PDF)]" so the href points to the actual file location
"/static/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf" instead of
"/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf"; modify the table cell containing
the document link accordingly so the rendered link uses the /static/assets path.
There was a problem hiding this comment.
Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!
There was a problem hiding this comment.
♻️ Duplicate comments (1)
src/pages/whitepaper.md (1)
303-303:⚠️ Potential issue | 🟡 MinorFix the PDF link path to match the actual file location.
The PDF link still references
/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf, but according to previous verification, the file exists at/static/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf. This broken link will result in a 404 error for users attempting to access the whitepaper.🔗 Proposed fix for the PDF path
-| v1.2 | 2025-11-14 | Current | [YELLOW MiCA White Paper v1.2 (PDF)](/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf) | +| v1.2 | 2025-11-14 | Current | [YELLOW MiCA White Paper v1.2 (PDF)](/static/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf) |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/pages/whitepaper.md` at line 303, Update the PDF link in the markdown table row that contains "[YELLOW MiCA White Paper v1.2 (PDF)]" so it points to the actual file location by changing the href from "/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf" to "/static/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf"; ensure the table row text for version v1.2 (the line shown in src/pages/whitepaper.md) is updated accordingly so the link resolves without a 404.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@src/pages/whitepaper.md`:
- Line 303: Update the PDF link in the markdown table row that contains "[YELLOW
MiCA White Paper v1.2 (PDF)]" so it points to the actual file location by
changing the href from "/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf" to
"/static/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf"; ensure the table row text
for version v1.2 (the line shown in src/pages/whitepaper.md) is updated
accordingly so the link resolves without a 404.
alessio
approved these changes
Mar 7, 2026
Contributor
alessio
left a comment
alessio
left a comment
There was a problem hiding this comment.
Minor comment to address. Other than that, looks good to me
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
2 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 by CodeRabbit
Documentation
Chores