docs(restructure): Implement HyperBEAM-first documentation approach#291
Merged
docs(restructure): Implement HyperBEAM-first documentation approach#291
Conversation
- Rename 'Migrating to HyperBEAM' to 'Working with HyperBEAM' in sidebar - Move 'Why Migrate' to 'Migration Guide' subsection for legacy users - Update 'State Exposure' to be feature-focused rather than migration-focused - Move dry-run documentation to deprecated section - Update getting-started.md to show HyperBEAM node first - Remove migration language from active documentation - Preserve all functional content while changing descriptive language only This makes HyperBEAM the default perspective for new users while maintaining migration support for existing Legacynet users.
- Create comprehensive quick start guide focused on HyperBEAM patterns - Prioritize state exposure over deprecated dry-run methods - Add to sidebar as first item in Welcome section - Include practical examples with counter and HTTP state reading - Provide clear next steps for learning more This gives new users a modern, HyperBEAM-first entry point to AO development.
- Consolidate welcome section from 5 pages to 3 pages: * Welcome & Quick Start (index.md) - immediate hands-on experience * Building with HyperBEAM (building.md) - modern patterns and techniques * Concepts & Migration (concepts.md) - deep dive and legacy support - Fix sidebar navigation highlighting by unlinking parent Welcome item - Update AOS version references from 1.12.1 to 2.0.9 - Rewrite migration guide to focus on state exposure as the key step - Reorganize file structure to be navigation-agnostic - Update all cross-references throughout codebase - Remove redundant getting-started.md and merge content into index.md This creates a streamlined, HyperBEAM-first experience that gets users building immediately while preserving important conceptual information.
- Create consolidated Getting Started guide that covers essential first steps - Reorganize guides into logical categories: * Core Concepts - fundamental patterns * Building Applications - actionable development guides * Migration - legacy migration and CLI tools - Keep 'Building Applications' as strong, actionable section title - Update all cross-references to new file locations - Fix sidebar navigation to reflect new structure - Resolve all dead links from reorganization This creates a clear learning progression: Getting Started → Core Concepts → Building Applications → Migration
Replace instances of 'State Exposure' and '**state exposure**' with more descriptive language like 'exposing process state via HTTP' to make documentation read more naturally and avoid treating it as a branded proprietary feature. Updated 8 files: - src/guides/hyperbeam/core/state-exposure.md - src/guides/hyperbeam/core/user-owned-processes.md - src/guides/hyperbeam/getting-started.md - src/guides/hyperbeam/migration.md - src/references/deprecated/dry-run.md - src/references/deprecated/index.md - src/welcome/building.md - src/welcome/concepts.md - src/welcome/index.md
Implement progressive disclosure strategy across 4 key files: - welcome/index.md: First exposure only (simple counter example) - welcome/building.md: Comprehensive patterns for real applications - getting-started.md: Learning progression with enhanced basics - state-exposure.md: Technical deep dive with cross-references Removed duplicate counter examples, token patterns, and chat examples. Each file now serves a specific purpose without redundancy while maintaining clear learning paths and comprehensive coverage.
Replace cache table syntax with direct patch message syntax for cleaner,
more intuitive state exposure examples.
Before:
Send({ device = 'patch@1.0', cache = { counter = Counter } })
After:
Send({ device = 'patch@1.0', counter = Counter })
Updated across 5 files:
- welcome/index.md
- welcome/building.md
- getting-started.md
- state-exposure.md
- migration.md
This makes the syntax more direct and eliminates unnecessary nesting.
Add three callouts highlighting AO's core technologies: - AO-Core: The protocol powering decentralized computation - HyperBEAM: Build with instant HTTP state access - Arweave Storage: Permanent computation with mathematical guarantees Implementation includes: - Responsive grid layout with hover effects - Dark mode support - Consistent styling with existing theme - Mobile-optimized design Callouts are positioned between main description and tutorial section for optimal user flow and visual hierarchy.
- Remove callouts from welcome/index.md (incorrect location) - Add Option Set 5 callouts to src/index.md (correct home page location) - Remove unnecessary CSS since VitePress home features have built-in styling - Update callouts to: AO-Core, HyperBEAM, Arweave Storage The callouts now appear on the main home page as intended, using VitePress's native home page features section.
- Remove src/guides/aoconnect/calling-dryrun.md (deprecated) - Remove permaweb glossary references from sidebar - Update sidebar configuration to remove both items - Regenerate LLMs.txt files to remove broken references This cleans up deprecated content and external dependencies while maintaining focus on current HyperBEAM patterns.
- Consolidate user-owned processes into state exposure documentation - Fix HTTP endpoint URLs from /cache/ to /compute/ across all files - Restructure concepts section with improved narrative flow - Add AO prefixes to distinguish from HyperBEAM content - Remove redundant sidebar entries and fix navigation - Update cross-references to point to consolidated documentation
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
This PR implements a comprehensive HyperBEAM-first documentation restructure to improve content organization, reduce redundancy, and provide clearer distinction between AO and HyperBEAM concepts.
Key Changes
URL Structure Corrections
Content Consolidation
user-owned-processes.mdcontent intostate-exposure.mdImpact
Testing
This restructure establishes a solid foundation for a HyperBEAM-first documentation approach while maintaining backward compatibility and improving overall user experience.