vitepress-usage

VitePress Usage for Code with PHP

Development Commands

# Start local development server
npm run dev
# Site available at http://localhost:5173

# Build static site for production
npm run build
# Output: docs/.vitepress/dist

# Preview production build locally
npm run preview
# Useful for testing before deployment

Project Structure

docs/
├── .vitepress/
│   ├── config.ts         # Site configuration
│   └── theme/            # Custom theme (if any)
├── index.md              # Homepage
├── public/
│   └── CNAME             # Custom domain configuration
└── series/
    └── <series-slug>/
        ├── index.md      # Series overview
        ├── chapters/     # All chapter markdown files
        │   ├── 00-chapter.md
        │   ├── 01-chapter.md
        │   └── ...
        └── code/         # Code examples colocated with content
            ├── 00-topic/
            ├── 01-topic/
            └── ...

Adding a New Series

Step 1: Create Series Directory Structure

# Create the series directories
mkdir -p docs/series/<series-slug>/{chapters,code}

# Create the series index
touch docs/series/<series-slug>/index.md

Step 2: Create Series Index

The series index must include:

1. Comprehensive overview (4-6 paragraphs)
2. Who This Is For section
3. Prerequisites (software, time, skills)
4. What You'll Build (deliverables)
5. Learning Objectives
6. How This Series Works (methodology)
7. Learning Path Overview (visual diagram)
8. Quick Start (5-minute example)
9. Chapters (organized by parts with descriptions)
10. FAQ
11. Getting Help
12. Related Resources

See docs/series/php-basics/index.md as the reference template.

Step 3: Update VitePress Config

Edit docs/.vitepress/config.ts:

// Add to nav
nav: [
  // ... existing items
  {
    text: 'Series Name',
    link: '/series/series-slug/'
  }
],

// Add sidebar configuration
sidebar: {
  // ... existing sidebars
  '/series/series-slug/': [
    {
      text: 'Series Name',
      items: [
        {
          text: 'Overview',
          link: '/series/series-slug/'
        },
        {
          text: 'Part 1: Section Name',
          collapsed: false,
          items: [
            {
              text: '00 — Chapter Title',
              link: '/series/series-slug/chapters/00-chapter-slug'
            },
            {
              text: '01 — Chapter Title',
              link: '/series/series-slug/chapters/01-chapter-slug'
            }
          ]
        }
      ]
    }
  ]
}