Reorganize subnet docs #23
Conversation
Add changelogs and repositories reference
WalkthroughDocumentation reorganization: Deleted repository documentation from components, created new resource files for repositories and subnet generator placeholder, added navigation tiles to overview page, expanded changelog with new versions (v2.1.0, v2.0.0), and restructured mkdocs.yml navigation with new "Deployment and Usage" and "Resources" groupings. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
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 (1)
mkdocs.yml (1)
128-128: Critical: Changelog path mismatch in navigation.Line 128 references the changelog at the outdated path
./subnet/install_guide/changelog.md, but line 138 correctly references the new location at./subnet/resources/changelog.md. This path conflict will cause a 404 error for users accessing the Deployment Guide → Changelog link.Apply this diff to correct the path on line 128:
- Deployment Guide: - Launch a Subnet: ./subnet/install_guide/launch_subnet.md - Multi-Machines Deployment: ./subnet/install_guide/multi_machines_deployment.md - Exposing Subnet Frontend: ./subnet/install_guide/exposing_services_frontend.md - Configs Explanation: ./subnet/install_guide/config_explanation.md - Common Issues and Troubleshooting: ./subnet/install_guide/common_issues.md - FAQ: ./subnet/install_guide/faq.md - - Subnet Deployment Generator Changelog: ./subnet/install_guide/changelog.md + - Subnet Deployment Generator Changelog: ./subnet/resources/changelog.mdAlternatively, if you intend to keep the changelog reference in both locations (Deployment Guide and Resources), you may remove it from line 128 to avoid duplication.
Also applies to: 138-138
🧹 Nitpick comments (1)
docs/subnet/components/subnet_generator.md (1)
1-1: Verify the placeholder file intent.This file contains only "placeholder" text and is not currently referenced in mkdocs.yml. Confirm whether this is intentional scaffolding for future content or if it needs completion before merge.
If content needs to be added, I can help generate documentation based on the subnet architecture described in overview.md.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
docs/subnet/components/repos.md(0 hunks)docs/subnet/components/subnet_generator.md(1 hunks)docs/subnet/overview.md(1 hunks)docs/subnet/resources/changelog.md(1 hunks)docs/subnet/resources/repos.md(1 hunks)mkdocs.yml(2 hunks)
💤 Files with no reviewable changes (1)
- docs/subnet/components/repos.md
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
docs/subnet/resources/repos.md
7-7: Bare URL used
(MD034, no-bare-urls)
9-9: Bare URL used
(MD034, no-bare-urls)
11-11: Bare URL used
(MD034, no-bare-urls)
13-13: Bare URL used
(MD034, no-bare-urls)
15-15: Bare URL used
(MD034, no-bare-urls)
17-17: Bare URL used
(MD034, no-bare-urls)
🔇 Additional comments (2)
docs/subnet/resources/changelog.md (1)
7-23: Changelog entries look good.The v2.1.0 and v2.0.0 entries are well-formatted and clearly document feature additions and improvements. Both entries use the same release date (2025/09/23)—confirm this is intentional and reflects actual release timing.
mkdocs.yml (1)
110-139: Navigation restructuring is well-organized.The new structure clearly separates concerns: Overview (design context), Deployment and Usage (operational guides), and Resources (references). This improves information architecture and user navigation flow.
|
|
||
|
|
||
| <div class="section-body"> | ||
| <a href="../components/subnet_chain/" class="grid-item"> |
There was a problem hiding this comment.
🧩 Analysis chain
Verify relative navigation paths resolve correctly.
The navigation tiles use relative paths (../components/subnet_chain/ and ../install_guide/launch_subnet/) to link to subnet documentation. Confirm these paths resolve correctly in the generated MkDocs site based on the restructured navigation hierarchy.
Run the following script to verify the markdown files exist and path references are valid:
Also applies to: 47-47
🏁 Script executed:
#!/bin/bash
# Description: Verify that referenced files exist and check mkdocs structure
# Check if referenced markdown files exist
echo "Checking referenced files..."
test -f docs/subnet/components/subnet_chain.md && echo "✓ Subnet Chain file exists" || echo "✗ Subnet Chain file NOT found"
test -f docs/subnet/install_guide/launch_subnet.md && echo "✓ Launch Subnet file exists" || echo "✗ Launch Subnet file NOT found"
# Check mkdocs.yml navigation structure for path consistency
echo -e "\nChecking mkdocs.yml references..."
grep -n "subnet_chain.md\|launch_subnet.md" mkdocs.ymlLength of output: 253
Fix relative navigation paths to use correct directory traversal.
The relative paths use ../ which incorrectly navigate to the root level instead of staying within the subnet directory. Update lines 43 and 47 to use ./ prefix:
- Line 43: Change
../components/subnet_chain/to./components/subnet_chain/ - Line 47: Change
../install_guide/launch_subnet/to./install_guide/launch_subnet/
From the generated MkDocs site at /subnet/overview/, the ../ prefix goes up to the root level, causing links to resolve to /components/subnet_chain/ and /install_guide/launch_subnet/ instead of /subnet/components/subnet_chain/ and /subnet/install_guide/launch_subnet/. The ./ prefix correctly keeps navigation within the subnet namespace.
🤖 Prompt for AI Agents
In docs/subnet/overview.md around lines 43 and 47, the relative links use "../"
which climbs to the site root and produces incorrect URLs; change line 43 from
"../components/subnet_chain/" to "./components/subnet_chain/" and line 47 from
"../install_guide/launch_subnet/" to "./install_guide/launch_subnet/" so the
links remain under the /subnet/ namespace and resolve to
/subnet/components/subnet_chain/ and /subnet/install_guide/launch_subnet/.
| Subnet Generator/Deployment Wizard: https://github.com/XinFinOrg/Subnet-Deployment | ||
|
|
||
| Subnet Blockchain Node: https://github.com/XinFinOrg/XDC-Subnet | ||
|
|
||
| Relayer: https://github.com/XinFinOrg/XDC-Relayer | ||
|
|
||
| Checkpoint Smart Contract (CSC): https://github.com/XinFinOrg/XDC-CSC | ||
|
|
||
| XDC-Zero Cross-chain Framework: https://github.com/XinFinOrg/XDC-Zero | ||
|
|
||
| Subnet UI: https://github.com/XinFinOrg/subnet-stats-service |
There was a problem hiding this comment.
Wrap bare URLs with markdown link syntax.
All repository URLs are flagged by markdownlint (MD034) as bare URLs. Wrap them in markdown link syntax to comply with linting standards.
Apply this diff to wrap URLs as proper markdown links:
## Subnet Repositories
-Subnet Generator/Deployment Wizard: https://github.com/XinFinOrg/Subnet-Deployment
+[Subnet Generator/Deployment Wizard](https://github.com/XinFinOrg/Subnet-Deployment)
-Subnet Blockchain Node: https://github.com/XinFinOrg/XDC-Subnet
+[Subnet Blockchain Node](https://github.com/XinFinOrg/XDC-Subnet)
-Relayer: https://github.com/XinFinOrg/XDC-Relayer
+[Relayer](https://github.com/XinFinOrg/XDC-Relayer)
-Checkpoint Smart Contract (CSC): https://github.com/XinFinOrg/XDC-CSC
+[Checkpoint Smart Contract (CSC)](https://github.com/XinFinOrg/XDC-CSC)
-XDC-Zero Cross-chain Framework: https://github.com/XinFinOrg/XDC-Zero
+[XDC-Zero Cross-chain Framework](https://github.com/XinFinOrg/XDC-Zero)
-Subnet UI: https://github.com/XinFinOrg/subnet-stats-service
+[Subnet UI](https://github.com/XinFinOrg/subnet-stats-service)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Subnet Generator/Deployment Wizard: https://github.com/XinFinOrg/Subnet-Deployment | |
| Subnet Blockchain Node: https://github.com/XinFinOrg/XDC-Subnet | |
| Relayer: https://github.com/XinFinOrg/XDC-Relayer | |
| Checkpoint Smart Contract (CSC): https://github.com/XinFinOrg/XDC-CSC | |
| XDC-Zero Cross-chain Framework: https://github.com/XinFinOrg/XDC-Zero | |
| Subnet UI: https://github.com/XinFinOrg/subnet-stats-service | |
| [Subnet Generator/Deployment Wizard](https://github.com/XinFinOrg/Subnet-Deployment) | |
| [Subnet Blockchain Node](https://github.com/XinFinOrg/XDC-Subnet) | |
| [Relayer](https://github.com/XinFinOrg/XDC-Relayer) | |
| [Checkpoint Smart Contract (CSC)](https://github.com/XinFinOrg/XDC-CSC) | |
| [XDC-Zero Cross-chain Framework](https://github.com/XinFinOrg/XDC-Zero) | |
| [Subnet UI](https://github.com/XinFinOrg/subnet-stats-service) |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
7-7: Bare URL used
(MD034, no-bare-urls)
9-9: Bare URL used
(MD034, no-bare-urls)
11-11: Bare URL used
(MD034, no-bare-urls)
13-13: Bare URL used
(MD034, no-bare-urls)
15-15: Bare URL used
(MD034, no-bare-urls)
17-17: Bare URL used
(MD034, no-bare-urls)
🤖 Prompt for AI Agents
In docs/subnet/resources/repos.md around lines 7 to 17, the listed repository
URLs are bare and trigger markdownlint MD034; wrap each URL in markdown link
syntax by replacing plain URLs with the format [Repository Name](https://...)
for each entry (e.g., Subnet Generator/Deployment Wizard -> [Subnet
Generator/Deployment Wizard](https://github.com/XinFinOrg/Subnet-Deployment)),
doing the same for Subnet Blockchain Node, Relayer, Checkpoint Smart Contract
(CSC), XDC-Zero Cross-chain Framework, and Subnet UI so all links comply with
linting.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.