tools-only TASK-13: Web Documentation Site
Status: 📋 Planning Priority: High Estimated Effort: 2-3 weeks (MVP), 6 weeks (complete) Created: 2025-10-19 Target Version: v3.1.0
🎯 Objective
Create a professional web documentation site for Navigator to:
- Improve discoverability and onboarding
- Showcase features with interactive demos
- Provide searchable reference for all 12 skills
- Build community around Navigator ecosystem
📊 Success Criteria
- Live documentation site at custom domain
- All 12 skills documented with examples
- Interactive token savings calculator
- 2-minute demo video
- Searchable documentation (Algolia)
- Mobile-responsive design
- <3s page load time
- Automated deployment pipeline
🏗️ Architecture
Tech Stack
Framework: VitePress (Vue-powered static site generator)
- Markdown-based content
- Vue 3 for interactive components
- Built-in search
- Dark mode support
Hosting: Vercel
- Zero-config deployment
- Automatic preview deployments
- Free for open source
- Global CDN
Search: Algolia DocSearch (free for open source)
Analytics: Plausible (optional, privacy-friendly)
📂 Site Structure
docs/
├── .vitepress/
│ ├── config.ts # Site configuration
│ ├── theme/
│ │ ├── index.ts # Custom theme
│ │ ├── components/
│ │ │ ├── TokenCalculator.vue
│ │ │ ├── SkillCard.vue
│ │ │ ├── BenchmarkChart.vue
│ │ │ └── CodeComparison.vue
│ │ └── styles/
│ │ └── custom.css
│ └── components/ # Global components
│
├── public/ # Static assets
│ ├── videos/
│ ├── images/
│ └── favicon.ico
│
├── index.md # Home page
│
├── getting-started/
│ ├── index.md # Installation
│ ├── first-session.md # Walkthrough
│ ├── your-first-skill.md # Tutorial
│ └── migration-v3.md # v2.3 → v3.0
│
├── concepts/
│ ├── index.md # Overview
│ ├── token-optimization.md # Deep dive
│ ├── skills-vs-agents.md # Comparison
│ ├── context-markers.md # Explanation
│ └── on-demand-loading.md # Pattern
│
├── skills/
│ ├── index.md # All 12 skills overview
│ ├── nav-start.md
│ ├── nav-marker.md
│ ├── nav-compact.md
│ ├── nav-task.md
│ ├── nav-sop.md
│ ├── nav-skill-creator.md
│ ├── plugin-slash-command.md
│ ├── frontend-component.md
│ ├── backend-endpoint.md
│ ├── database-migration.md
│ ├── backend-test.md
│ └── frontend-test.md
│
├── guides/
│ ├── daily-workflow.md
│ ├── creating-custom-skills.md
│ ├── team-collaboration.md
│ ├── multi-project-setup.md
│ ├── pm-tool-integration.md
│ └── performance-tuning.md
│
├── examples/
│ ├── index.md # Gallery
│ ├── nextjs-saas.md # Full walkthrough
│ ├── react-component.md # Example
│ ├── api-endpoint.md # Example
│ ├── database-migration.md # Example
│ └── custom-skills.md # 5+ examples
│
├── benchmarks/
│ └── index.md # Performance data
│
├── configuration/
│ ├── nav-config.md # .nav-config.json reference
│ ├── pm-tools.md # Linear, GitHub, etc.
│ ├── team-chat.md # Slack, Discord, etc.
│ └── templates.md # Custom templates
│
├── troubleshooting/
│ ├── index.md # Common issues
│ ├── installation.md
│ ├── skills.md
│ ├── markers.md
│ └── pm-tools.md
│
├── community/
│ ├── contributing.md
│ ├── skill-marketplace.md
│ ├── showcase.md
│ └── changelog.md
│
└── api/
├── skill-structure.md
├── functions.md
├── templates.md
└── hooks.md
🎨 Custom Components
1. TokenCalculator.vue
Interactive calculator showing token savings:
Inputs:
- Project size (Small/Medium/Large)
- Documentation pages (slider)
- Work type (Feature/Debug/Research)
Outputs:
- Traditional approach: X tokens
- Navigator approach: Y tokens
- Savings: Z tokens (%)
- Sessions before restart: N
2. SkillCard.vue
Reusable skill reference card:
Props:
- Skill name
- Description
- Trigger phrases
- Auto-invoke conditions
- Example usage
- Related skills
3. BenchmarkChart.vue
Charts showing real performance data:
Types:
- Token usage over time
- Cache efficiency
- Session length comparison
- Before/after bar charts
4. CodeComparison.vue
Side-by-side code comparison:
Props:
- Before code (traditional)
- After code (Navigator)
- Language
- Highlight lines
📝 Content Migration Plan
Existing Content to Adapt
From README.md:
- ✅ Home page hero
- ✅ Feature overview
- ✅ Quick start
- ✅ Skills list
From START-HERE.md:
- ✅ Getting started guide
- ✅ Project structure
From CLAUDE.md:
- ✅ Workflow guides
- ✅ Best practices
- ✅ Forbidden actions
From docs/ folder:
- ✅ Quick start
- ✅ Configuration
- ✅ Deployment
From examples/:
- ✅ Next.js SaaS walkthrough
From .claude-plugin/skills/:
- ✅ All 12 SKILL.md files → skill reference pages
New Content to Create
Critical (MVP):
- Home page (new design)
- Token optimization deep dive
- Skills vs Agents comparison
- Context markers explanation
- Interactive tutorials
- 2-minute demo video
- FAQ (10+ entries)
Important (Phase 2):
- 6 essential guides
- Benchmarks page with real data
- Troubleshooting database
- Migration guides
Nice-to-Have (Phase 3):
- Blog posts / case studies
- User showcase
- Skill marketplace
- Advanced API docs
🚀 Implementation Plan
Phase 1: MVP (Week 1-2)
Week 1: Setup + Core Pages
Day 1-2: VitePress Setup
# Initialize VitePress in docs/
npm init vitepress@latest docs
cd docs && npm install
# Configure custom theme
# Create .vitepress/config.ts
# Setup navigation structure
# Configure Algolia search
Day 3-4: Home + Getting Started
# Create index.md (home page)
# Create getting-started/ pages
# Add installation steps
# Add first session walkthrough
Day 5-6: Skills Reference
# Script to auto-generate skill pages from SKILL.md files
# Create skills/index.md overview
# Create individual skill pages (12)
Day 7: Deploy
# Setup Vercel project
# Configure custom domain
# Test deployment pipeline
# QA all pages
Week 2: Interactive Features + Content
Day 1-2: Core Concepts
# Create concepts/ pages (4)
# Add diagrams/illustrations
# Write token optimization deep dive
Day 3-4: Interactive Components
# Build TokenCalculator.vue
# Build SkillCard.vue
# Integrate components into pages
# Test responsiveness
Day 5: Demo Video
# Record 2-minute walkthrough
# Edit and upload to YouTube
# Embed in home page
Day 6-7: Polish + Launch
# QA all pages
# Mobile testing
# Performance optimization
# Announce launch
MVP Deliverables:
- ✅ Live site at custom domain
- ✅ Home page with video demo
- ✅ Getting started guide
- ✅ All 12 skills documented
- ✅ 4 core concept pages
- ✅ Interactive token calculator
- ✅ Algolia search
- ✅ Mobile-responsive
Phase 2: Growth (Week 3-6)
Week 3: Guides
- Daily workflow guide
- Creating custom skills guide
- Team collaboration guide
- Multi-project setup guide
- PM tool integration guides
- Performance tuning guide
Week 4: Examples
- Examples gallery page
- Next.js SaaS full walkthrough
- React component example
- API endpoint example
- Database migration example
- Custom skill examples (5+)
Week 5: Benchmarks
- Collect real session data
- Create BenchmarkChart.vue component
- Build benchmarks page
- Add interactive charts
- Document methodology
Week 6: Configuration + Troubleshooting
- Configuration reference pages
- PM tool integration details
- Troubleshooting FAQ (20+ entries)
- Common errors database
- Debug checklists
Phase 2 Deliverables:
- ✅ 6 essential guides
- ✅ 5+ working examples
- ✅ Benchmarks dashboard
- ✅ Complete configuration docs
- ✅ Comprehensive troubleshooting
Phase 3: Community (Week 7-12)
Week 7-8: Advanced Docs
- API reference (skill structure)
- Predefined functions API
- Template system docs
- Plugin hooks documentation
Week 9-10: Community Features
- Contributing guide
- Skill marketplace (submission form)
- Community showcase page
- GitHub Discussions integration
Week 11-12: Blog + Content
- Blog setup (VitePress blog)
- First case study
- Migration stories
- Performance analysis posts
Phase 3 Deliverables:
- ✅ Complete API documentation
- ✅ Community contribution system
- ✅ Skill marketplace v1
- ✅ Active blog
🔧 Development Setup
Prerequisites
# Node.js 18+ required
node --version # v18.0.0+
# Install pnpm (faster than npm)
npm install -g pnpm
Local Development
# Install dependencies
cd docs
pnpm install
# Start dev server
pnpm docs:dev
# → http://localhost:5173
# Build for production
pnpm docs:build
# Preview production build
pnpm docs:preview
Scripts to Create
scripts/generate-skill-docs.js
// Reads .claude-plugin/skills/*/SKILL.md
// Generates docs/skills/*.md
// Auto-updates skills/index.md
scripts/update-changelog.js
// Reads git tags and commits
// Generates docs/community/changelog.md
scripts/optimize-images.js
// Compresses images in docs/public/
// Generates WebP versions
📊 VitePress Configuration
.vitepress/config.ts
import { defineConfig } from 'vitepress'
export default defineConfig({
title: 'Navigator',
description: 'Self-improving Claude Code plugin',
themeConfig: {
logo: '/logo.svg',
nav: [
{ text: 'Home', link: '/' },
{ text: 'Getting Started', link: '/getting-started/' },
{ text: 'Skills', link: '/skills/' },
{ text: 'Guides', link: '/guides/' },
{ text: 'Examples', link: '/examples/' },
],
sidebar: {
'/getting-started/': [
{
text: 'Getting Started',
items: [
{ text: 'Installation', link: '/getting-started/' },
{ text: 'First Session', link: '/getting-started/first-session' },
{ text: 'Your First Skill', link: '/getting-started/your-first-skill' },
{ text: 'Migration Guide', link: '/getting-started/migration-v3' },
]
}
],
'/skills/': [
{
text: 'Core Skills',
items: [
{ text: 'Overview', link: '/skills/' },
{ text: 'nav-start', link: '/skills/nav-start' },
{ text: 'nav-marker', link: '/skills/nav-marker' },
{ text: 'nav-compact', link: '/skills/nav-compact' },
{ text: 'nav-task', link: '/skills/nav-task' },
{ text: 'nav-sop', link: '/skills/nav-sop' },
{ text: 'nav-skill-creator', link: '/skills/nav-skill-creator' },
]
},
{
text: 'Project Skills',
items: [
{ text: 'frontend-component', link: '/skills/frontend-component' },
{ text: 'backend-endpoint', link: '/skills/backend-endpoint' },
{ text: 'database-migration', link: '/skills/database-migration' },
{ text: 'backend-test', link: '/skills/backend-test' },
{ text: 'frontend-test', link: '/skills/frontend-test' },
]
}
],
// ... more sidebar configs
},
socialLinks: [
{ icon: 'github', link: 'https://github.com/alekspetrov/navigator' }
],
search: {
provider: 'algolia',
options: {
appId: 'YOUR_APP_ID',
apiKey: 'YOUR_API_KEY',
indexName: 'navigator'
}
},
footer: {
message: 'Released under the MIT License.',
copyright: 'Copyright © 2025 Navigator'
}
},
head: [
['link', { rel: 'icon', type: 'image/svg+xml', href: '/logo.svg' }],
['meta', { name: 'theme-color', content: '#646cff' }],
['meta', { property: 'og:type', content: 'website' }],
['meta', { property: 'og:title', content: 'Navigator' }],
['meta', { property: 'og:description', content: 'Self-improving Claude Code plugin' }],
],
markdown: {
theme: {
light: 'github-light',
dark: 'github-dark'
},
lineNumbers: true
}
})
🚢 Deployment
Vercel Setup
Connect GitHub repo to Vercel
- Import project at vercel.com
- Select Navigator repository
- Framework preset: VitePress
- Root directory:
docs - Build command:
npm run docs:build - Output directory:
.vitepress/dist
Configure custom domain
- Add domain in Vercel settings
- Update DNS records (A/CNAME)
- Enable HTTPS (automatic)
Environment variables (if needed)
ALGOLIA_APP_IDALGOLIA_API_KEYPLAUSIBLE_DOMAIN(optional)
CI/CD Pipeline
GitHub Actions (.github/workflows/docs.yml):
name: Deploy Documentation
on:
push:
branches: [main]
paths:
- 'docs/**'
- '.claude-plugin/skills/**'
pull_request:
branches: [main]
paths:
- 'docs/**'
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 20
cache: 'pnpm'
cache-dependency-path: docs/pnpm-lock.yaml
- name: Install pnpm
run: npm install -g pnpm
- name: Install dependencies
run: cd docs && pnpm install
- name: Generate skill docs
run: node scripts/generate-skill-docs.js
- name: Build documentation
run: cd docs && pnpm docs:build
- name: Deploy to Vercel (Production)
if: github.ref == 'refs/heads/main'
uses: amondnet/vercel-action@v25
with:
vercel-token: ${{ secrets.VERCEL_TOKEN }}
vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
vercel-args: '--prod'
working-directory: docs/.vitepress/dist
- name: Deploy to Vercel (Preview)
if: github.event_name == 'pull_request'
uses: amondnet/vercel-action@v25
with:
vercel-token: ${{ secrets.VERCEL_TOKEN }}
vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
working-directory: docs/.vitepress/dist
📊 Analytics & Monitoring
Plausible Analytics (Recommended)
Why Plausible:
- Privacy-friendly (GDPR compliant)
- Lightweight (<1KB script)
- No cookies
- Beautiful dashboard
Setup:
<!-- docs/.vitepress/theme/index.ts -->
<script defer data-domain="navigator.dev" src="https://plausible.io/js/script.js"></script>
Track:
- Page views
- Unique visitors
- Bounce rate
- Top pages
- Referral sources
- Search queries (custom events)
Performance Monitoring
Lighthouse CI (in GitHub Actions):
- name: Run Lighthouse
uses: treosh/lighthouse-ci-action@v10
with:
urls: |
https://navigator.dev
https://navigator.dev/getting-started/
https://navigator.dev/skills/
uploadArtifacts: true
Targets:
- Performance: >95
- Accessibility: 100
- Best Practices: 100
- SEO: 100
📈 Success Metrics
Launch Targets (Week 2)
- Site live at custom domain
- <3s page load time
- 100% mobile responsive
- Algolia search working
- 50+ pages of content
Month 1 Targets
- 500+ unique visitors
- 50+ GitHub stars
- 3+ community contributions
- <2% bounce rate on Getting Started
Month 3 Targets
- 2,000+ unique visitors
- 200+ GitHub stars
- 10+ custom skills shared
- 50+ search queries/day
Month 6 Targets
- 5,000+ unique visitors
- 500+ GitHub stars
- Active skill marketplace
- 3+ blog posts published
🔍 SEO Strategy
On-Page SEO
Title Tags:
- Home: "Navigator - Self-Improving Claude Code Plugin"
- Skills: "nav-start Skill | Navigator Documentation"
- Guides: "Creating Custom Skills | Navigator Guides"
Meta Descriptions:
- Unique per page
- 150-160 characters
- Include keywords: "Claude Code", "token optimization", "AI development"
Open Graph:
<meta property="og:title" content="Navigator Documentation" />
<meta property="og:description" content="..." />
<meta property="og:image" content="https://navigator.dev/og-image.png" />
Content Strategy
Target Keywords:
- "Claude Code plugin"
- "token optimization"
- "AI development tools"
- "context-efficient AI"
- "Claude Code documentation"
- "AI agent tools"
Internal Linking:
- Link between related skills
- Link guides to skill references
- Link examples to relevant guides
Sitemap
Auto-generated by VitePress, submit to:
- Google Search Console
- Bing Webmaster Tools
🎯 Future Enhancements
Q1 2026
- Video tutorials for each skill (12 videos)
- Interactive playground (try skills in browser)
- Skill marketplace with ratings/reviews
- Community-contributed examples gallery
Q2 2026
- API playground (test predefined functions)
- Template customization tool (visual editor)
- Performance profiler (analyze your projects)
- AI-powered documentation search (semantic)
Q3 2026
- Multi-language support (i18n)
- Integration showcase (Linear, GitHub, etc.)
- Case studies from real projects
- Certification program (Navigator expert)
🚧 Risks & Mitigations
Risk 1: Content Maintenance Burden
Risk: Documentation falls out of sync with code Mitigation:
- Auto-generate skill docs from SKILL.md files
- CI/CD checks for doc updates on skill changes
- Quarterly doc review scheduled
Risk 2: Search Quality
Risk: Algolia search doesn't find relevant results Mitigation:
- Careful keyword selection
- Regular search query analysis
- Fallback to local search if needed
Risk 3: Performance Issues
Risk: Site becomes slow with more content Mitigation:
- Static site generation (VitePress)
- Image optimization pipeline
- Lazy loading for heavy components
- CDN (Vercel)
Risk 4: Low Adoption
Risk: Users don't discover the docs Mitigation:
- Promote on GitHub README
- Share in Claude Code community
- SEO optimization
- Social media announcement
📚 Resources
Design Inspiration
- VitePress docs: https://vitepress.dev
- Tailwind CSS docs: https://tailwindcss.com/docs
- Nuxt docs: https://nuxt.com
- Astro docs: https://docs.astro.build
Tools
- VitePress: https://vitepress.dev
- Algolia DocSearch: https://docsearch.algolia.com
- Plausible Analytics: https://plausible.io
- Vercel: https://vercel.com
Community
- VitePress Discord: https://discord.gg/vitepress
- Claude Code GitHub: https://github.com/anthropics/claude-code
✅ Done Criteria
This task is complete when:
- Documentation site is live at custom domain
- All 12 skills documented with examples
- Interactive token calculator working
- 2-minute demo video embedded
- Algolia search configured and working
- Mobile-responsive (tested on 3+ devices)
- Page load time <3s (Lighthouse >95)
- Automated deployment pipeline working
- 50+ pages of content published
- Analytics tracking configured
- GitHub README links to docs site
- Announcement published (GitHub Discussions, social media)
This task establishes Navigator's web presence and significantly improves discoverability and user onboarding.