Plan: Docusaurus Documentation Website

IMPLEMENTATION RULES: Before implementing this plan, read and follow:

WORKFLOW.md - The implementation process

PLANS.md - Plan structure and best practices

Status: Completed ✅

Goal: Create a professional, engaging documentation website using Docusaurus to attract developers to devcontainer-toolbox.

Last Updated: 2026-01-16

Priority: High

Context

Current docs in /docs are plain Markdown
Want professional "product" feel to sell the idea to developers
Each tool should have its own detailed page
AI can auto-generate tool pages when new tools are created
Site should build automatically on push via GitHub Actions
All development runs inside the devcontainer (Node.js already available)

Phase 1: Docusaurus Setup — ✅ DONE

Goal: Initialize Docusaurus in /website folder with basic config.

Create /website folder structure
Initialize Docusaurus project (use npx, not global install)
Configure docusaurus.config.ts:
- Site title, tagline, URL
- GitHub repo link
- Theme colors matching project identity
Configure sidebars.ts for auto-generated sidebar
Add .gitignore entries for node_modules, build output
Update HomepageFeatures component with project-relevant content
Create placeholder docs (index.md, getting-started.md, tools.md, commands.md)
Test dev server works

Starting the dev server (run inside VS Code terminal connected to devcontainer):

cd /workspace/website
npm run start -- --host 0.0.0.0

The --host 0.0.0.0 flag is required for VS Code port forwarding to work. Without it, the server only binds to localhost inside the container and won't be accessible from the host.

Other useful commands:

npm run build    # Production build
npm run serve    # Serve production build locally

Validation:

npm run start -- --host 0.0.0.0 opens local preview at localhost:3000/devcontainer-toolbox/
npm run build completes without errors
No broken links or missing images

Phase 2: Landing Page — ✅ DONE

Goal: Create an engaging home page that sells the project.

Design hero section:
- Headline: "DevContainer Toolbox"
- Subheadline: "One command. Full dev environment. Any project."
- CTA buttons: "Get Started", "View on GitHub"
Add features section (3 key benefits):
- Works Everywhere (Windows, Mac, Linux)
- 20+ Tools Ready
- AI-Ready Development
Add the AI demo GIF (teaser) with link to full docs
Add quick install code block (Mac/Linux and Windows PowerShell)

Components created:

src/components/QuickInstall/ - Install command code blocks
src/components/AiDemo/ - AI demo GIF section

Validation:

Landing page looks professional
CTAs link to correct pages

Phase 3: Migrate Core Docs — ✅ DONE

Goal: Move existing documentation into Docusaurus structure.

Create docs structure:

website/docs/
├── index.md                  (1) - Home/Quick Start
├── what-are-devcontainers.md (2) - Educational intro
├── getting-started.md        (3) - Full install guide
├── commands.md               (4) - Command reference
├── configuration.md          (5) - Config files
├── troubleshooting.md        (6) - Common issues
└── tools/
    └── index.md              (7) - Tools overview

Create what-are-devcontainers.md - educational content:
- What is a container? (simple explanation)
- What is a devcontainer? (VS Code integration)
- Why use devcontainers? (benefits for teams)
- How it works (diagram: your code + container = consistent env)
- Common misconceptions
- Links to VS Code docs and tutorials
Copy and adapt existing content from /docs:
- Added frontmatter (title, sidebar_position)
- Removed manual back links (Docusaurus handles navigation)
- Updated internal links to use Docusaurus format
Set up sidebar categories (auto-generated from folder structure)

Validation:

All core docs render correctly
Navigation works
No broken links

Phase 4: Update Doc Generation Scripts — ✅ DONE

Goal: Update dev-docs.sh to write to website/docs/.

Update .devcontainer/manage/dev-docs.sh:
- Changed OUTPUT_FILE to website/docs/tools/index.md
- Changed OUTPUT_FILE_DETAILS to website/docs/tools-details.md
- Changed OUTPUT_FILE_COMMANDS to website/docs/commands.md
- Added Docusaurus frontmatter (sidebar_position, sidebar_label)
- Added Docusaurus admonitions for "auto-generated" notices
Update CI workflow to check website/docs/
Delete old /docs root-level files (kept docs/contributors/ and docs/ai-developer/)
Test dev-docs generates to correct location
Update all path references:
- README.md - updated links to website/docs/
- CLAUDE.md - updated documentation section
- docs/ai-developer/CREATING-SCRIPTS.md - updated dev-docs output path
- .devcontainer.extend/README-devcontainer-extended.md - updated tools link

Validation:

dev-docs writes to website/docs/
Generated pages render correctly with frontmatter
Admonitions show "Auto-generated" notices
All path references updated (historical files in completed plans left as-is)

Phase 5: Tool Detail Pages — ✅ DONE

Goal: Create individual pages for each tool with detailed information.

Validation:

Tool pages show in sidebar under "Tools"
Content is helpful and complete

Phase 6: AI Development Section — ✅ DONE

Goal: Showcase AI-assisted development as a key feature.

Create /docs/ai-development/ section:
- index.md - Main AI development overview with GIF
- workflow.md - Step-by-step implementation workflow
- creating-plans.md - Plan templates and best practices
- _category_.json - Sidebar configuration (position 3)
Feature prominently in navigation (sidebar position 3, after "What Are DevContainers?")
Link from landing page (AiDemo component now links to /docs/ai-development)
Copied ai-make-plan.png to website/static/img/

Validation:

AI section is easy to find
GIF displays correctly
Links work correctly

Phase 7: Contributor Docs — ✅ DONE

Goal: Migrate contributor documentation.

Create /docs/contributors/ section:
- _category_.json - Sidebar config (position 9)
- index.md - Contributing overview
- adding-tools.md - How to add new tools
- testing.md - Testing guide
- ci-cd.md - CI/CD and GitHub Actions
- releasing.md - Version management and releases
Mark as separate category in sidebar (position 9, after Tool Details)
Links to detailed docs in repository for advanced topics

Validation:

Contributor docs accessible but separate from user docs
Key content adapted for website

Phase 8: GitHub Actions Deployment — ✅ DONE

Goal: Auto-deploy to GitHub Pages on push to main.

Create .github/workflows/deploy-docs.yml:
- Triggers on push to main when website/ changes
- Uses Node.js 20 to build Docusaurus
- Deploys using actions/deploy-pages@v4
- Supports manual trigger via workflow_dispatch
Document GitHub Pages configuration (see below)

GitHub Pages Setup (one-time, manual):

Go to repository Settings → Pages
Under "Build and deployment", select "GitHub Actions" as source
The workflow will deploy automatically on next push to main

Validation:

Workflow file created
Push to main triggers build (requires merge to test)
Site live at https://dct.sovereignsky.no/

Phase 9: Polish and Launch — ✅ DONE

Goal: Final touches before announcing.

Add search (local search using @easyops-cn/docusaurus-search-local)
Review all pages for broken links (fixed anchor links in tools-details.md)
Add favicon and social card image (fixed social card reference)
Test on mobile (user to verify after deployment)
Update root README.md with link to docs site
Consolidate all documentation into website/docs/
Create contributor documentation subsections
Update website/README.md with correct devcontainer commands

Changes made:

Installed @easyops-cn/docusaurus-search-local package
Added themes config with search plugin to docusaurus.config.ts
Fixed social card reference (img/docusaurus-social-card.jpg)
Fixed broken anchors in tools-details.md (2 dashes instead of 3)
Fixed anchor generation in dev-docs.sh for future regenerations
Updated README.md documentation links to point to live site
Documentation consolidation:
- Moved docs/contributors/ to website/docs/contributors/ with new subsections:
  - scripts/ - Install script creation guide
  - architecture/ - System architecture, categories, libraries, menu system
  - services/ - Service scripts overview
- Moved docs/ai-developer/ to website/docs/ai-developer/
- Moved docs/ai-docs/ to website/docs/ai-docs/
- Moved media files to website/static/ (GIFs to img/, .cast to recordings/)
- Created docs/README.md explaining docs are now in website/
- Added Docusaurus frontmatter and _category_.json to all moved folders
- Fixed all broken links after reorganization
- Created website/docs/contributors/website.md - Docusaurus workflow guide
- Updated website/README.md with correct npm commands and --host 0.0.0.0 flag

Validation:

Search works (search box appears in navbar)
Social sharing shows correct preview (fixed image reference)
npm run build completes with no broken links
All documentation consolidated in website/docs/

Future Enhancements (Not in this plan)

Blog for announcements
Versioned docs
i18n translations
Custom React components
Algolia DocSearch (when traffic justifies)

Files to Create

File	Purpose
`website/`	Docusaurus project root
`website/docusaurus.config.js`	Main configuration
`website/sidebars.js`	Sidebar navigation
`website/src/pages/index.js`	Custom landing page
`website/docs/**`	Documentation content
`.github/workflows/deploy-docs.yml`	Auto-deployment

Dependencies

Node.js (already in devcontainer base image)
npm (already in devcontainer base image)
No additional install scripts needed

Risks

Risk	Mitigation
Migration breaks links	Test all links before launch
Build fails in CI	Test locally first, check Node version
GIFs too large	Already optimized, verified < 10MB

Success Criteria

Professional landing page that "sells" the project
Easy navigation to all documentation
Individual tool pages with detailed guides
AI development prominently featured
Auto-deploys on push
Works on mobile

Status: Completed ✅​

Context​

Phase 1: Docusaurus Setup — ✅ DONE​

Phase 2: Landing Page — ✅ DONE​

Phase 3: Migrate Core Docs — ✅ DONE​

Phase 4: Update Doc Generation Scripts — ✅ DONE​

Phase 5: Tool Detail Pages — ✅ DONE​

Phase 6: AI Development Section — ✅ DONE​

Phase 7: Contributor Docs — ✅ DONE​

Phase 8: GitHub Actions Deployment — ✅ DONE​

Phase 9: Polish and Launch — ✅ DONE​

Future Enhancements (Not in this plan)​

Files to Create​

Dependencies​

Risks​

Success Criteria​

Status: Completed ✅

Context

Phase 1: Docusaurus Setup — ✅ DONE

Phase 2: Landing Page — ✅ DONE

Phase 3: Migrate Core Docs — ✅ DONE

Phase 4: Update Doc Generation Scripts — ✅ DONE

Phase 5: Tool Detail Pages — ✅ DONE

Phase 6: AI Development Section — ✅ DONE

Phase 7: Contributor Docs — ✅ DONE

Phase 8: GitHub Actions Deployment — ✅ DONE

Phase 9: Polish and Launch — ✅ DONE

Future Enhancements (Not in this plan)

Files to Create

Dependencies

Risks

Success Criteria