Stylus docs plan A #3050
Stylus docs plan A #3050
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Update all image width preset classes (.img-20px through .img-900px) to include max-width: 100%, ensuring images scale down appropriately on smaller viewports while maintaining their specified width on larger screens.
Replace markdown image syntax with ImageZoom component for the two storage diagrams (storage types hierarchy and storage slots layout) to provide better responsive behavior, zoom functionality, and accessibility. Added descriptive alt text and captions for improved user experience.
Created editable draw.io file with original tree layout: - Root "Storage Types" node branching to 3 categories - Primitives category with 7 storage type nodes - Collections category with 3 container type nodes - Custom Struct category with 2 declaration style nodes - Original color scheme preserved (purple, blue, green, orange) This file can be opened in draw.io for visual editing and exported to various image formats (SVG, PNG, PDF).
There was a problem hiding this comment.
Pull request overview
This PR implements a comprehensive reorganization of the Stylus documentation structure, moving from a flat organization to a hierarchical "Plan A" structure with dedicated sections for fundamentals, guides, CLI tools, best practices, troubleshooting, concepts, advanced topics, and reference materials.
Changes:
- Reorganized Stylus documentation into a new hierarchical structure with 8 main sections
- Added extensive new documentation including troubleshooting guide (591 lines), security best practices (499 lines), and gas optimization guide (536 lines)
- Created reusable content partials for common setup instructions
- Updated internal links throughout the documentation to reflect new structure
- Removed legacy files (sync-stylus-content.js, homepage components, old overview files)
Reviewed changes
Copilot reviewed 66 out of 79 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/sync-stylus-content.js | Removed 671-line legacy Stylus content sync script |
| src/pages/index.js, index.module.css | Removed custom homepage components |
| docs/stylus/troubleshooting/common-issues.mdx | Added comprehensive troubleshooting guide with solutions for common Stylus development issues |
| docs/stylus/best-practices/*.mdx | Added security and gas optimization best practices documentation |
| docs/stylus/partials/*.mdx | Created reusable setup instruction partials for Rust, Docker, and cargo-stylus |
| docs/stylus/fundamentals/*.mdx | Reorganized fundamental concepts with new prerequisites and learning path guides |
| docs/stylus/cli-tools/*.mdx | Consolidated CLI tools documentation with command reference and verification guides |
| Multiple link updates | Updated internal documentation links to match new structure |
| package.json | Removed sync-stylus-content script from build commands |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| // Manual SDK file constants | ||
| const INDEX_FILENAME = 'index.mdx'; | ||
| const INDEX_FILENAME = 'introduction.mdx'; |
There was a problem hiding this comment.
The change from 'index.mdx' to 'introduction.mdx' should be documented in the PR description or accompanied by a comment explaining why this naming change was made, as it affects the SDK documentation structure.
| alt: 'Arbitrum Logo', | ||
| src: 'img/logo.svg', | ||
| href: '/get-started/overview', | ||
| href: '/', |
There was a problem hiding this comment.
Changing the logo href from '/get-started/overview' to '/' should be verified to ensure the homepage exists and provides appropriate content, since the old homepage components (index.js, index.module.css) were removed in this PR.
| href: '/', | |
| href: '/get-started/overview', |
docs/stylus/
│
├── gentle-introduction.mdx
├── quickstart.mdx
├── using-cli.mdx (legacy)
│
├── fundamentals/
│ ├── category.yml
│ ├── choose-your-path.mdx [NEW - Phase 4]
│ ├── prerequisites.mdx [Phase 3]
│ ├── project-structure.mdx
│ ├── contracts.mdx [DIAGRAM: Lifecycle]
│ ├── global-variables-and-functions.mdx
│ ├── testing-contracts.mdx
│ └── data-types/
│ ├── primitives.mdx
│ ├── compound-types.mdx
│ ├── storage.mdx [DIAGRAMS: Hierarchy + Layout]
│ └── conversions-between-types.mdx
│
├── guides/
│ ├── category.yml
│ ├── using-constructors.mdx
│ ├── using-inheritance.mdx
│ ├── importing-interfaces.mdx [DIAGRAM: Cross-Contract Calls]
│ ├── exporting-abi.mdx
│ ├── optimizing-binaries.mdx
│ ├── caching-contracts.mdx
│ ├── deploying-non-rust-wasm-contracts.mdx
│ └── adding-support-for-new-languages.mdx
│
├── cli-tools/
│ ├── category.yml
│ ├── overview.mdx
│ ├── check-and-deploy.mdx
│ ├── verify-contracts.mdx
│ ├── debugging-tx.mdx
│ └── commands-reference.mdx
│
├── best-practices/ [NEW - Phase 4]
│ ├── category.yml
│ ├── security.mdx (501 lines)
│ └── gas-optimization.mdx [DIAGRAM: Performance Comparison] (548 lines)
│
├── troubleshooting/ [NEW - Phase 4]
│ ├── category.yml
│ ├── common-issues.mdx (591 lines)
│ └── troubleshooting-building-stylus.md (legacy)
│
├── concepts/
│ ├── category.yml
│ ├── webassembly.mdx [DIAGRAMS: Pipeline + Binary + Memory]
│ ├── activation.mdx [DIAGRAM: Deployment]
│ ├── gas-metering.mdx
│ ├── vm-differences.mdx (renamed in Phase 3)
│ └── public-preview-expectations.mdx
│
├── advanced/
│ ├── category.yml
│ ├── rust-to-solidity-differences.mdx (renamed in Phase 3)
│ ├── minimal-entrypoint-contracts.mdx
│ ├── hostio-exports.mdx
│ └── recommended-libraries.mdx
│
├── reference/
│ ├── category.yml
│ ├── overview.mdx
│ ├── opcode-hostio-pricing.mdx
│ └── rust-sdk-guide.md
│
├── partials/ (Reusable Content)
│ ├── _setup-rust-toolchain.mdx
│ ├── _setup-cargo-stylus.mdx
│ ├── _setup-docker-nitro.mdx
│ ├── _stylus-faucets.mdx
│ ├── _stylus-no-multi-inheritance-banner-partial.mdx
│ └── _stylus-public-preview-banner-partial.md