Consolidate Deno Deploy API Documentation into Main Docs Site

[abhi-parate-st3]

Currently, there's a fragmentation in Deno's documentation ecosystem where the deployctl CLI API documentation (particularly for subhosting) is hosted separately at apidocs.deno.com, while the main documentation resides at docs.deno.com. This separation creates unnecessary friction in the developer experience.

Current State

1. Main documentation: docs.deno.com

   • Contains general Deno Deploy documentation
   • Limited coverage of deployctl CLI features
   • No comprehensive API reference for subhosting

2. API documentation: apidocs.deno.com

   • Houses detailed API specifications
   • Contains critical subhosting API information
   • Separate from main documentation flow

Problems This Creates

1. Discoverability Issues

   • Developers may miss critical API documentation
   • No clear path from main docs to API reference
   • Search functionality doesn't cover both domains

2. User Experience Impact

   • Context switching between different documentation sites
   • Inconsistent navigation patterns
   • Extra time spent searching for information
   • Risk of using outdated information if docs aren't in sync

3. Maintenance Challenges

   • Multiple documentation sources to maintain
   • Potential for inconsistencies between sites
   • Higher risk of documentation drift
   • Duplicate effort in updates and maintenance

Proposed Solution

1. Documentation Integration

Integrate API documentation into the main docs site in one of two ways:

Option A: Full Integration

docs.deno.com/
 ├── deploy/
 │   ├── manual/
 │   └── api/          # New section for API docs
 │       ├── deployctl/
 │       └── subhosting/

Option B: Seamless Navigation

• Add prominent links to API documentation
• Implement unified search across both documentation sets
• Maintain consistent styling and navigation

2. Specific Improvements

1. New API Reference Section

   • Comprehensive deployctl command reference
   • Detailed subhosting API documentation
   • Interactive API examples
   • Authentication and authorization details

2. Navigation Enhancements

   • Clear breadcrumb navigation
   • Contextual links between related content
   • Improved search functionality

3. Content Organization

   • Logical grouping of related APIs
   • Clear versioning information
   • Deprecation notices when applicable

Benefits

1. Developer Experience

   • Single source of truth for all documentation
   • Reduced time searching for information
   • Improved onboarding experience
   • Better discovery of available features

2. Maintenance

   • Simplified documentation updates
   • Reduced risk of inconsistencies
   • Easier version control
   • Streamlined review process

3. SEO and Accessibility

   • Improved search engine visibility
   • Better internal linking
   • Consistent accessibility standards