Documentation restructuring: token bridging, messaging, and reference organization#3122
Draft
Documentation restructuring: token bridging, messaging, and reference organization#3122
Conversation
Phase 2 of deep-dives restructure: - Move overview, ETH bridging, and ERC-20 bridging docs from build-decentralized-apps/token-bridging/ to how-arbitrum-works/token-bridging/ - Remove duplicate token bridge content from l1-to-l2-messaging.mdx (141 lines), replace with cross-reference - Update sidebars: add Token bridging category to howItWorksSidebar, remove from buildAppsSidebar - Add 6 new redirects and update 5 existing redirects in vercel.json - Update all cross-references across 11 files - Fix relative import path for _token-compatibility.mdx partial - Update overview.mdx text to focus on architecture/concepts (appropriate for how-arbitrum-works section) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
Phase 3 of deep-dives restructure: - Move transaction-lifecycle.mdx from how-arbitrum-works/deep-dives/ to build-decentralized-apps/ - Change content_type from concept to how-to (this is procedural content about submitting transactions) - Add to buildAppsSidebar after "Estimate gas" - Add redirect in vercel.json - Update 3 cross-references in l1-to-l2-messaging.mdx, inside-arbitrum-nitro.mdx, and arbitrum-chain-finality.mdx Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
Phase 4 of deep-dives restructure: - Move bridge-tokens-programmatically/*.mdx files up one level to token-bridging/ - Update sidebars.js to remove nested category level (keep IDs flattened) - Add 8 new redirects in vercel.json for old bridge-tokens-programmatically/ paths - Update 5 existing redirects to point to new flattened paths - Update cross-references in 6 files (4 how-to guides + 2 concept docs) - Fix relative import path for _token-compatibility.mdx partial Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
Phase 5 of deep-dives restructure: - Create how-to-bridge-from-parent-chain.mdx with procedural content for parent-to-child bridging (ETH deposits, Delayed Inbox usage, retryable tickets) - Create how-to-bridge-to-parent-chain.mdx with procedural content for child-to-parent bridging (ETH withdrawals, ERC-20 withdrawals, outbox execution) - Add both new how-to guides to buildAppsSidebar after cross-chain-messaging - Update cross-chain-messaging.mdx to link to new how-to guides alongside protocol deep-dives - Add tip boxes to both deep-dive files pointing developers to the new how-to guides - Deep-dive files retain full conceptual content but now clearly direct developers to implementation guides Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
Follow-up to Phase 5: Remove how-to content from conceptual pages - Trimmed l1-to-l2-messaging.mdx: Removed detailed method signatures, parameter tables, and step-by-step procedures - Replaced procedural sections with concise conceptual explanations and links to how-to guides - Trimmed l2-to-l1-messaging.mdx: Removed detailed code examples and withdrawal procedures - Replaced with brief conceptual overviews linking to implementation guides - Deep-dives now focus purely on protocol concepts, architecture, and design rationale - All procedural "how-to" content now lives in dedicated how-to guides Changes to l1-to-l2-messaging.mdx: - Native token bridging: Removed depositEth method details - Delayed Inbox: Removed all method signatures for signed/unsigned messages - Retryable tickets: Condensed from ~130 lines to ~20 lines of pure concepts Changes to l2-to-l1-messaging.mdx: - Client flow: Removed step-by-step instructions - ETH/ERC-20 withdrawals: Removed procedural details, kept concepts Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
Add formal method signatures, parameter descriptions, and return values to both bridging how-to guides. This ensures all reference-level content removed from concept pages during Phase 5 is now available in the how-to guides, making them comprehensive implementation references. Changes: - how-to-bridge-from-parent-chain.mdx: Added all 4 unsigned message method variants, enhanced retryable ticket parameter descriptions with formulas and important notes about auto-redeem behavior - how-to-bridge-to-parent-chain.mdx: Added formal signatures for sendTxToL1, withdrawEth, constructOutboxProof, and executeTransaction with parameter and return value documentation This addresses the data loss concern by restoring complete reference information to how-to guides while keeping concept pages focused on protocol-level explanations. Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
Reduce duplication between arbos.mdx and gas-and-fees.mdx by replacing detailed gas pricing sections in arbos.mdx with a brief summary and cross-references to the comprehensive documentation. Changes: - arbos.mdx: Replaced 40 lines of gas pricing details with concise summary and cross-references to gas-and-fees.mdx and parent-chain-pricing.mdx - gas-and-fees.mdx: Added tip box in parent chain gas pricing section pointing to parent-chain-pricing.mdx reference for mathematical details This maintains gas-and-fees.mdx as the primary conceptual guide while establishing clear navigation to the technical reference for readers needing detailed mathematical formulas. Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
Reorganize token bridging documentation to clearly distinguish between one-time token configuration and ongoing deposit/withdraw operations. New structure: - Common operations (top-level): - get-started.mdx - overview and decision guide - deposit-tokens.mdx - how to deposit tokens - withdraw-tokens.mdx - how to withdraw tokens - Configuration (nested): - configure-token-bridging/setup-standard-gateway.mdx - configure-token-bridging/setup-generic-custom-gateway.mdx - configure-token-bridging/setup-custom-gateway.mdx Changes: - Created deposit-tokens.mdx and withdraw-tokens.mdx for common operations - Moved setup guides to configure-token-bridging/ subdirectory - Refactored setup guides to focus on configuration, not operations - Updated get-started.mdx to present clear "I want to use" vs "I want to configure" paths - Removed ERC-20 withdrawal content from how-to-bridge-to-parent-chain.mdx (now in dedicated token-bridging/withdraw-tokens.mdx) - Updated all cross-references and links - Updated sidebars.js with new nested structure - Added redirects for old URLs in vercel.json This organization makes it easier for users to find relevant guides: most users want deposit/withdraw, while token creators need configuration. Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
ETH bridging was misplaced in the "token-bridging" section (ETH is native currency, not an ERC-20 token) and duplicated content from the how-to guides. Changes: - Removed docs/how-arbitrum-works/token-bridging/eth-bridging.mdx - Added depositing ether diagram to how-to-bridge-from-parent-chain.mdx (withdrawing ether diagram was already in how-to-bridge-to-parent-chain.mdx) - Added framing text to l1-to-l2-messaging.mdx explaining that native token bridging is different from ERC-20 token bridging - Removed ETH bridging from token-bridging sidebar - Updated all redirects that pointed to eth-bridging.mdx to redirect to how-to-bridge-from-parent-chain.mdx instead - Updated overview.mdx link to point to native token bridging section All ETH bridging content is now consolidated in: - Concept: l1-to-l2-messaging.mdx (native token bridging section) - How-to deposits: how-to-bridge-from-parent-chain.mdx - How-to withdrawals: how-to-bridge-to-parent-chain.mdx Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
Document the faster validation commands to use instead of always running full yarn build (which takes 30-40s). Recommended workflow: 1. Quick validation: yarn lint:markdown && yarn format:check (~1-2s) 2. Link/structure checks: yarn start with hot reload 3. Final verification: yarn build before committing This will help future Claude instances iterate much faster when making documentation changes. Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
Moves token bridging content from separate category into Deep dives, combining overview.mdx and erc20-bridging.mdx into a single token-bridging.mdx file. Updates all references across 15 documentation files. Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
… docs Move geth.mdx, parent-chain-pricing.mdx, and stf-inputs.mdx from deep-dives/ to a new reference/ directory. Extract technical reference content from arbos.mdx into arbos-reference.mdx. Update all cross-references, sidebar navigation, and vercel.json redirects. Co-Authored-By: Claude Opus 4.6 <[email protected]>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
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
Comprehensive documentation restructuring to improve content organization and reduce redundancy across token bridging, cross-chain messaging, and technical reference sections.
Key Changes
Token Bridging Reorganization
Messaging Documentation
Reference Section
Documentation Support
Impact
Testing
🤖 Generated with Claude Code