docs: remove deprecated sections and migrate content for v1 release#132
Open
docs: remove deprecated sections and migrate content for v1 release#132
Conversation
Part 1 of YNU-864. Remove deprecated Learn pages (App Sessions, Session Keys, Message Envelope, Advanced section), Protocol App Layer (15 files), Protocol cross-layer flows/glossary/checklist, Guides section (after migrating migration-guide and multi-party-app-sessions to Build/SDK). Remove Guides from navbar and footer. Fix all broken links in current and versioned docs.
📝 WalkthroughWalkthroughThis PR comprehensively restructures the documentation site by removing substantial sections of guide and protocol documentation, reorganizing the Learn sidebar categories, and updating internal navigation links to use relative paths instead of absolute paths. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 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 docstrings
🧪 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 (1)
src/components/HomepageFeatures/index.tsx (1)
44-54:⚠️ Potential issue | 🟠 MajorMisleading "Run a Clearnode" feature tile.
The tile description promises "Set up and operate a clearnode to provide network services and contribute to decentralized infrastructure," but the link now points to the generic
/docs/learnpage instead of specific setup instructions.This creates a poor user experience where users clicking for clearnode setup instructions land on a general documentation homepage.
Recommended solutions:
- Update the description to reflect that detailed setup docs are not yet available
- Change the link to a more relevant target (e.g., architecture/clearnode concepts)
- Temporarily hide this tile until clearnode setup documentation is available
📝 Proposed fix: Update description to set accurate expectations
{ title: 'Run a Clearnode', imageSrc: require('@site/static/img/themes/light/icons/clearnode.png').default, imageSrcDark: require('@site/static/img/themes/dark/icons/clearnode.png').default, description: ( <> - Set up and operate a clearnode to provide network services - and contribute to decentralized infrastructure. + Learn about clearnodes and their role in providing network services + for decentralized infrastructure. Setup guides coming soon. </> ), link: '/docs/learn', },🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/components/HomepageFeatures/index.tsx` around lines 44 - 54, The "Run a Clearnode" feature entry (the object with title 'Run a Clearnode', imageSrc/imageSrcDark, description, link) points to the generic '/docs/learn' page which is misleading; either update the description JSX to set accurate expectations (e.g., "Concepts and roadmap for clearnode setup — detailed setup docs coming soon") and change the link to a more relevant page (e.g., '/docs/architecture/clearnode' or '/docs/learn/clearnode-concepts') or temporarily remove/hide this tile by removing it from the exported features array (or setting a flag like hidden: true) until full setup docs exist; make the change in the HomepageFeatures entry for 'Run a Clearnode'.
🧹 Nitpick comments (1)
versioned_docs/version-0.5.x/learn/core-concepts/state-channels-vs-l1-l2.mdx (1)
139-139: Inconsistent link style: absolute path used.Line 139 uses an absolute path (
/docs/protocol/architecture.mdx) while lines 140-141 use relative paths (../../protocol/...). For consistency with the rest of this file and the broader PR pattern of standardizing on relative paths in versioned docs, consider updating this to a relative path as well.♻️ Suggested fix for consistency
-- **[Architecture](/docs/protocol/architecture.mdx)** — System design and fund flows +- **[Architecture](../../protocol/architecture.mdx)** — System design and fund flows🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/learn/core-concepts/state-channels-vs-l1-l2.mdx` at line 139, Replace the absolute link "/docs/protocol/architecture.mdx" with the relative path used elsewhere in this doc (e.g., "../../protocol/architecture.mdx") so the Architecture link matches the relative linking convention; update the link text within the same list item (the "**[Architecture]...**" entry) to use the relative path.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/build/sdk/multi-party-app-sessions.mdx`:
- Around line 588-589: The "Further Reading" section was simplified to only
include "[Protocol] — Protocol specification and architecture" and "[SDK
Reference] — Complete SDK documentation", which reduces discoverability of
session-specific topics; update the "Further Reading" block (the section labeled
"Further Reading" that currently contains those two links) to either restore the
original four specific links (App Sessions concepts, app session methods,
client-side signing, and session keys) or, if you want to keep only the two
general links, add a short inline note under them pointing to where session key
management and signing workflows live (e.g., "For session key management and
signing workflows, see: App Sessions concepts and App session methods in the SDK
Reference and Client-side signing in Protocol docs"). Ensure the edit mentions
the specific pages by name so users can find them easily.
In `@docs/learn/core-concepts/challenge-response.mdx`:
- Line 155: Replace the single generic Protocol link in the sentence "For
technical implementation details, see the
[Protocol](/docs/protocol/introduction) section." with targeted links (or an
explanatory note) pointing to the specific deep-dive pages that were previously
present: Channel Lifecycle, Security Considerations, and Communication Flows (or
explicitly state where challenge-response closure-flow sequence diagrams live);
alternatively, if those pages were removed, update the Protocol introduction
page to prominently signpost or link to the challenge-response implementation
details and add a brief note here directing readers to that specific location.
---
Outside diff comments:
In `@src/components/HomepageFeatures/index.tsx`:
- Around line 44-54: The "Run a Clearnode" feature entry (the object with title
'Run a Clearnode', imageSrc/imageSrcDark, description, link) points to the
generic '/docs/learn' page which is misleading; either update the description
JSX to set accurate expectations (e.g., "Concepts and roadmap for clearnode
setup — detailed setup docs coming soon") and change the link to a more relevant
page (e.g., '/docs/architecture/clearnode' or '/docs/learn/clearnode-concepts')
or temporarily remove/hide this tile by removing it from the exported features
array (or setting a flag like hidden: true) until full setup docs exist; make
the change in the HomepageFeatures entry for 'Run a Clearnode'.
---
Nitpick comments:
In
`@versioned_docs/version-0.5.x/learn/core-concepts/state-channels-vs-l1-l2.mdx`:
- Line 139: Replace the absolute link "/docs/protocol/architecture.mdx" with the
relative path used elsewhere in this doc (e.g.,
"../../protocol/architecture.mdx") so the Architecture link matches the relative
linking convention; update the link text within the same list item (the
"**[Architecture]...**" entry) to use the relative path.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 3bd6563c-a40d-4556-bcce-8541defffb40
📒 Files selected for processing (56)
docs/build/getting-started/_category_.jsondocs/build/getting-started/key-terms.mdxdocs/build/getting-started/prerequisites.mdxdocs/build/getting-started/quickstart.mdxdocs/build/sdk/migration-guide.mddocs/build/sdk/multi-party-app-sessions.mdxdocs/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/advanced/_category_.jsondocs/learn/advanced/managing-session-keys.mdxdocs/learn/core-concepts/app-sessions.mdxdocs/learn/core-concepts/challenge-response.mdxdocs/learn/core-concepts/message-envelope.mdxdocs/learn/core-concepts/session-keys.mdxdocs/learn/core-concepts/state-channels-vs-l1-l2.mdxdocs/learn/index.mdxdocs/learn/introduction/architecture-at-a-glance.mdxdocs/learn/introduction/supported-chains.mdxdocs/learn/introduction/what-yellow-solves.mdxdocs/protocol/app-layer/_category_.jsondocs/protocol/app-layer/off-chain/_category_.jsondocs/protocol/app-layer/off-chain/app-sessions.mdxdocs/protocol/app-layer/off-chain/authentication.mdxdocs/protocol/app-layer/off-chain/channel-methods.mdxdocs/protocol/app-layer/off-chain/message-format.mdxdocs/protocol/app-layer/off-chain/overview.mdxdocs/protocol/app-layer/off-chain/queries.mdxdocs/protocol/app-layer/off-chain/transfers.mdxdocs/protocol/app-layer/on-chain/_category_.jsondocs/protocol/app-layer/on-chain/channel-lifecycle.mdxdocs/protocol/app-layer/on-chain/data-structures.mdxdocs/protocol/app-layer/on-chain/overview.mdxdocs/protocol/app-layer/on-chain/security.mdxdocs/protocol/app-layer/on-chain/signature-formats.mdxdocs/protocol/communication-flows.mdxdocs/protocol/decentralized-layer/overview.mdxdocs/protocol/glossary.mdxdocs/protocol/implementation-checklist.mdxdocs/protocol/introduction.mdxdocs/protocol/protocol-reference.mdxdocusaurus.config.tssidebars.tssrc/components/HomepageFeatures/index.tsxversioned_docs/version-0.5.x/guides/index.mdversioned_docs/version-0.5.x/guides/multi-party-app-sessions.mdxversioned_docs/version-0.5.x/learn/core-concepts/app-sessions.mdxversioned_docs/version-0.5.x/learn/core-concepts/challenge-response.mdxversioned_docs/version-0.5.x/learn/core-concepts/message-envelope.mdxversioned_docs/version-0.5.x/learn/core-concepts/session-keys.mdxversioned_docs/version-0.5.x/learn/core-concepts/state-channels-vs-l1-l2.mdxversioned_docs/version-0.5.x/learn/getting-started/key-terms.mdxversioned_docs/version-0.5.x/learn/introduction/architecture-at-a-glance.mdxversioned_docs/version-0.5.x/learn/introduction/supported-chains.mdx
💤 Files with no reviewable changes (33)
- docs/learn/advanced/category.json
- docs/protocol/app-layer/off-chain/category.json
- docs/guides/index.md
- docs/protocol/app-layer/on-chain/category.json
- docs/protocol/app-layer/category.json
- docs/learn/core-concepts/state-channels-vs-l1-l2.mdx
- docs/guides/manuals/category.json
- docusaurus.config.ts
- docs/protocol/glossary.mdx
- docs/guides/manuals/request-blockchain-support.md
- docs/protocol/introduction.mdx
- docs/learn/core-concepts/app-sessions.mdx
- docs/protocol/app-layer/on-chain/signature-formats.mdx
- docs/protocol/app-layer/on-chain/security.mdx
- docs/learn/advanced/managing-session-keys.mdx
- docs/learn/index.mdx
- docs/protocol/app-layer/on-chain/data-structures.mdx
- docs/protocol/app-layer/off-chain/authentication.mdx
- docs/learn/core-concepts/message-envelope.mdx
- docs/protocol/app-layer/off-chain/overview.mdx
- docs/guides/manuals/request-asset-support.md
- docs/protocol/communication-flows.mdx
- docs/learn/core-concepts/session-keys.mdx
- docs/protocol/app-layer/off-chain/app-sessions.mdx
- docs/protocol/app-layer/off-chain/message-format.mdx
- docs/guides/manuals/running-clearnode-locally.md
- docs/protocol/app-layer/off-chain/queries.mdx
- docs/protocol/app-layer/on-chain/overview.mdx
- docs/protocol/implementation-checklist.mdx
- sidebars.ts
- docs/protocol/app-layer/off-chain/transfers.mdx
- docs/protocol/app-layer/on-chain/channel-lifecycle.mdx
- docs/protocol/app-layer/off-chain/channel-methods.mdx
Comment on lines
+588
to
+589
| - [Protocol](/docs/protocol/introduction) — Protocol specification and architecture | ||
| - [SDK Reference](/docs/build/sdk) — Complete SDK documentation |
There was a problem hiding this comment.
Consider the impact of reducing navigation specificity.
The previous "Further Reading" section provided direct links to four specific topics (App Sessions concepts, app session methods, client-side signing, and session keys). Replacing these with two general links (Protocol introduction and SDK reference) may reduce discoverability for users seeking specific information.
If the specific pages were intentionally removed, consider adding brief inline guidance about where to find topics like session key management and signing workflows within the general documentation.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/build/sdk/multi-party-app-sessions.mdx` around lines 588 - 589, The
"Further Reading" section was simplified to only include "[Protocol] — Protocol
specification and architecture" and "[SDK Reference] — Complete SDK
documentation", which reduces discoverability of session-specific topics; update
the "Further Reading" block (the section labeled "Further Reading" that
currently contains those two links) to either restore the original four specific
links (App Sessions concepts, app session methods, client-side signing, and
session keys) or, if you want to keep only the two general links, add a short
inline note under them pointing to where session key management and signing
workflows live (e.g., "For session key management and signing workflows, see:
App Sessions concepts and App session methods in the SDK Reference and
Client-side signing in Protocol docs"). Ensure the edit mentions the specific
pages by name so users can find them easily.
| - **[Channel Lifecycle](/docs/protocol/app-layer/on-chain/channel-lifecycle.mdx)** — Full state machine | ||
| - **[Security Considerations](/docs/protocol/app-layer/on-chain/security.mdx)** — Threat model and best practices | ||
| - **[Communication Flows](/docs/protocol/communication-flows.mdx#challenge-response-closure-flow)** — Sequence diagrams | ||
| For technical implementation details, see the [Protocol](/docs/protocol/introduction) section. |
There was a problem hiding this comment.
Consider restoring specific deep-dive navigation.
The previous version offered targeted links to Channel Lifecycle, Security Considerations, and Communication Flows. Replacing these with a single generic Protocol link may reduce discoverability for users seeking specific technical details like "challenge-response closure-flow sequence diagrams."
If those pages were removed intentionally, consider adding a note explaining where users can find challenge-response implementation details, or ensure the Protocol introduction page clearly signposts those topics.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/learn/core-concepts/challenge-response.mdx` at line 155, Replace the
single generic Protocol link in the sentence "For technical implementation
details, see the [Protocol](/docs/protocol/introduction) section." with targeted
links (or an explanatory note) pointing to the specific deep-dive pages that
were previously present: Channel Lifecycle, Security Considerations, and
Communication Flows (or explicitly state where challenge-response closure-flow
sequence diagrams live); alternatively, if those pages were removed, update the
Protocol introduction page to prominently signpost or link to the
challenge-response implementation details and add a brief note here directing
readers to that specific location.
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
1 participant
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
Part 1 of YNU-864 (Prepare Docs for production release of Nitrolite v1) — Removals and Migrations.
56 files changed, ~8000 lines removed
Remaining pre-existing broken links (out of scope):
build/api/contracts/*— auto-generated API docs with broken/src/paths0.5.x/protocol/app-layer/off-chain/channel-methods— internal 0.5.x linkTest plan
npm run buildsucceedsSummary by CodeRabbit
Documentation
Chores