delorex/test-repo
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(docs): migrate from docsify to vitepress

Browse Source 
- Move CSS styles from theme to public directory
- Update documentation structure and build commands
- Add new VitePress configuration and theme setup
This commit is contained in:
sanbuphy
2026-01-12 18:51:37 +08:00
parent 2b762868df
commit 99c1fb9ba8
3 changed files with 188 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+101 -51
View File
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Project Overview
This is **Easy-Vibe**, an educational curriculum for learning AI Vibe Coding from zero to advanced levels. It's a documentation-based project using Docsify to serve educational content about AI-assisted software development.
This is **Easy-Vibe**, an educational curriculum for learning AI Vibe Coding from zero to advanced levels. It's a documentation-based project using **VitePress** to serve educational content about AI-assisted software development.
The curriculum follows a progressive four-stage structure:
@@ -19,17 +19,21 @@ The curriculum follows a progressive four-stage structure:
```bash
npm install # Install dependencies (first time only)
npm run dev # Start docsify server on port 3000
# or
npm start # Same as npm run dev
npm run dev # Start VitePress dev server
```
The documentation will be available at `http://localhost:3000`
The documentation will be available at `http://localhost:5173` (VitePress default port)
### Build/Run Commands
- `npm run dev` - Serves the documentation using docsify-cli on port 3000
- No build step required - docsify serves markdown files directly
- `npm run dev` - Start VitePress development server with hot reload
- `npm run build` - Build static site for production (outputs to `docs/.vitepress/dist`)
- `npm run preview` - Preview production build locally
- `npm run format` - Format code using Prettier
### Node Version Requirement
- Node.js >= 18.0.0 required (specified in package.json `engines`)
## Project Architecture
@@ -37,20 +41,30 @@ The documentation will be available at `http://localhost:3000`
```
easy-vibe/
├── docs/ # Main documentation content (served by docsify)
│ ├── index.html # Docsify configuration and plugins
│ ├── _sidebar.md # Sidebar navigation structure
│ ├── README.md # Homepage (symlink to root README.md)
├── docs/ # Main documentation content (served by VitePress)
│ ├── .vitepress/ # VitePress configuration and theme
│ │ ├── config.mjs # Site configuration (nav, sidebar, plugins)
│ │ ├── theme/ # Custom theme extensions
│ │ │ ├── Layout.vue # Override default layout with typewriter effect
│ │ │ ├── index.js # Theme setup (Viewer.js, TypeIt, image optimization)
│ │ │ └── style.css # Custom CSS overrides
│ │ ├── dist/ # Production build output (generated)
│ │ └── cache/ # VitePress cache (generated)
│ ├── index.md # Homepage
│ ├── public/ # Static assets (logo.png, etc.)
│ ├── assets/ # Symlink to ../assets
│ ├── stage-0/ # Stage 0 content (幼儿园)
│ ├── stage-1/ # Stage 1 content (AI 产品经理)
│ ├── stage-2/ # Stage 2 content (初中级开发工程师)
│ ├── stage-3/ # Stage 3 content (高级开发工程师)
│ ├── appendix/ # Reference materials (AI capability dictionary)
│ ├── examples/ # Practical examples and tutorials
│ ├── examples/ # Practical examples and tutorials (legacy)
│ ├── extra/ # Additional knowledge (Git, API, RAG, etc.)
│ ├── guide/ # Course guide
│ └── project/ # Legacy project documentation
├── assets/ # Images and static assets (symlinked in docs/)
├── assets/ # Images and static assets
├── package.json # Project dependencies and scripts
├── vercel.json # Vercel deployment configuration
└── README.md # Project overview and contribution guide
```
@@ -60,47 +74,83 @@ Each stage follows a numbered chapter structure:
```
stage-{N}/
└── {N}.{M}-{chapter-name}/
├── index.md # Main content file
└── images/ # Chapter-specific images
└── {category or chapter-dir}/
└── index.md # Main content file (or .md file directly)
```
Example: `stage-1/1.1-introduction-to-ai-ide/index.md`
Examples:
- `stage-1/1.1-introduction-to-ai-ide/index.md`
- `stage-2/backend/2.1-what-is-api/extra2/extra2-what-is-api.md`
### Documentation System (Docsify)
**Note**: Content files may use either `index.md` or direct `.md` files depending on the chapter structure.
The project uses **Docsify** with the following key configuration in `docs/index.html`:
### Documentation System (VitePress)
- **Single Sidebar**: `loadSidebar: true` with `/_sidebar.md` alias for all routes
- **Search**: Full-text search across all documentation
- **Dark Mode**: Theme toggle with localStorage persistence
- **Image Viewer**: Viewer.js for image zoom/rotate/flip
- **Code Copy**: Copy code button on all code blocks
- **Pagination**: Previous/Next navigation between chapters
- **Word Count**: Chinese word count display on each page
The project uses **VitePress 2.0.0-alpha.15** with these key features:
**Configuration** (`docs/.vitepress/config.mjs`):
- **Single Sidebar**: Route-based sidebars configured per path prefix (`/stage-0/`, `/stage-1/`, etc.)
- **Navigation**: Top nav with links to each stage and appendix
- **Search**: Local search via `minisearch` (no external API required)
- **Dark Mode**: Built-in VitePress theme with toggle
**Custom Theme** (`docs/.vitepress/theme/`):
- **Image Viewer**: Viewer.js integration for zoom/rotate/flip on all images
- **Typewriter Effect**: TypeIt.js for homepage hero tagline animation
- **Image Optimization**: Automatic image height classes based on aspect ratio
- **Custom Layout**: Extends default theme with `Layout.vue` override
**Key Theme Behaviors**:
- Images with aspect ratio > 1.2 get height-limited classes (tall/very-tall/ultra-tall)
- Viewer.js initialized on `.vp-doc` container on each route change
- Typewriter effect only activates on homepage when `frontmatter.hero.tagline` is an array
### Sidebar Management
The sidebar is defined in `docs/_sidebar.md`. When adding new chapters:
The sidebar is defined in `docs/.vitepress/config.mjs`. When adding new chapters:
1. Add the chapter entry to the appropriate stage section
2. Follow the existing pattern: `* [Chapter Title](stage-{N}/{chapter-dir}/index.md)`
3. Ensure relative paths match the actual directory structure
1. Locate the appropriate route prefix section (`/stage-0/`, `/stage-1/`, etc.)
2. Add a new object with `text` (display name) and `link` (relative path)
3. For nested items, use `items` array with `collapsed: true|false`
4. **Links should not include `.md` extension** - VitePress handles this
5. Links should not include `index` - use directory path with trailing slash
Example pattern:
```javascript
{
text: 'Chapter Title',
link: '/stage-1/chapter-directory/' // Note: trailing slash, no .md
}
```
### Asset Management
- Static assets are in `/assets/` at the root level
- Chapter-specific images go in `stage-{N}/{chapter-dir}/images/`
- Images are referenced with relative paths from the markdown file location
- Global CSS limits image display to max 80% width, 300px height with centered alignment
- Root-level static assets are in `/assets/` at project root
- Public files (favicon, logo) go in `docs/public/`
- Images are referenced with relative paths from markdown file location
- VitePress serves `docs/assets` as symlink to `../assets`
- Image optimization is automatic via theme (height-limited classes based on aspect ratio)
### Deployment
**Vercel** (vercel.json):
- Build command: `npm run build`
- Output directory: `docs/.vitepress/dist`
- Framework: vitepress
**Preview Production Build**:
```bash
npm run build
npm run preview # Preview built site locally
```
### Legacy Content Structure
The project maintains three legacy sections in the sidebar for backward compatibility:
The project maintains three legacy sections for backward compatibility:
1. **Project 文档** (`project/`): Older chapter-based tutorials
2. **Extra 扩展知识** (`extra/`): Supplementary topics (Git, APIs, RAG, deployment)
3. **Examples 实战案例** (`examples/`): Practical tutorials (some moved to stage-3)
1. **Project 文档** (`project/`): Older chapter-based tutorials (migrated to Stage 2)
2. **Extra 扩展知识** (`extra/`): Supplementary topics - Git, APIs, RAG, deployment (migrated to Stage 2/3)
3. **Examples 实战案例** (`examples/`): Practical tutorials (migrated to Stage 0/3)
When updating content, prefer integrating into the stage structure over adding to legacy sections.
@@ -108,11 +158,10 @@ When updating content, prefer integrating into the stage structure over adding t
### Writing New Chapters
1. Create directory: `docs/stage-{N}/{N}.{M}-{chapter-name}/`
2. Create `index.md` with chapter content
3. Add images subdirectory if needed: `images/`
4. Update `docs/_sidebar.md` with the new entry
5. Follow Chinese language conventions (this is a Chinese curriculum)
1. Create directory: `docs/stage-{N}/{chapter-directory}/`
2. Create `index.md` or direct `.md` file with chapter content
3. Update `docs/.vitepress/config.mjs` sidebar with the new entry
4. Follow Chinese language conventions (this is a Chinese curriculum)
### Content Status Markers
@@ -123,15 +172,15 @@ In README.md, use these status indicators:
### File Naming Conventions
- Use kebab-case for directories: `1.1-introduction-to-ai-ide`
- Use `index.md` for primary content files
- Images use descriptive names in their respective chapter directories
- Use kebab-case for directories: `1.1-introduction-to-ai-ide`, `frontend`, `backend`
- Content can be either `index.md` in a directory or a direct `.md` file
- Images use descriptive names; can be in chapter subdirectories or root `/assets/`
## Permissions
The project has configured bash permissions in `.claude/settings.local.json`:
- File operations: `which`, `find`, `mv`, `tree`, `cat`, `curl`, `lsof`
- File operations: `which`, `find`, `mv`, `tree`, `cat`, `curl`, `lsof`, `mkdir`, `cp`, `ls`
- Process management: `xargs ps`, `kill`
- Development: `npm run dev`
@@ -140,14 +189,15 @@ The project has configured bash permissions in `.claude/settings.local.json`:
- **Educational Focus**: This is curriculum content, not application code
- **Target Audience**: Beginners to advanced developers learning AI-assisted programming
- **Language**: Primary content is in Chinese
- **No Build Pipeline**: Docsify serves markdown directly, no compilation needed
- **Build Pipeline**: VitePress requires build step for production (`npm run build`)
- **Git Workflow**: Content changes should preserve formatting and structure
- **Asset Paths**: Always use relative paths from markdown file location
When making changes:
- Preserve the Docsify configuration in `docs/index.html`
- Maintain sidebar structure consistency
- Preserve the VitePress configuration in `docs/.vitepress/config.mjs`
- Maintain sidebar structure consistency in config.mjs
- Test locally with `npm run dev` before committing
- Check that image links work correctly
- Ensure dark mode styles are not broken
- Ensure theme customizations in `.vitepress/theme/` are not broken
- Run `npm run format` before committing code changes (uses Prettier: no semicolons, single quotes)
docs/.vitepress/theme/index.js
-1
View File
@@ -4,7 +4,6 @@ import 'viewerjs/dist/viewer.css'
import TypeIt from 'typeit'
import { onMounted, watch, nextTick } from 'vue'
import { useRoute, useData } from 'vitepress'
import './style.css'
export default {
extends: DefaultTheme,
docs/public/style.css
+78
View File
@@ -0,0 +1,78 @@
:root {
/* 调整侧边栏分组之间的间距 */
--vp-sidebar-nav-section-gap: 8px;
}
/* 减少一级标题（如"前端开发"）底部的间距 */
.VPSidebarItem.level-0 {
padding-bottom: 4px !important;
}
/* 减少一级标题文字与下方子菜单的间距 */
.VPSidebarItem.level-0 > .item {
padding-bottom: 2px !important;
}
/* 调整子菜单项之间的间距 - 针对所有层级 */
.VPSidebarItem.level-1 .item,
.VPSidebarItem.level-2 .item,
.VPSidebarItem.level-3 .item,
.VPSidebarItem.level-4 .item {
padding-top: 2px !important;
padding-bottom: 2px !important;
min-height: 24px !important; /* 强制减小最小高度 */
}
/* 针对可能存在的特定类名进行覆盖，确保紧凑 */
.VPSidebarGroup {
padding-top: 6px !important;
padding-bottom: 6px !important;
}
/* 进一步压缩分组标题与第一项之间的间距 */
.VPSidebarItem.level-0 + .VPSidebarItem.level-1 {
margin-top: -2px !important;
}
/* 压缩分组标题本身的行高 */
.VPSidebarItem.level-0 .text {
line-height: 1.3 !important;
}
/* 压缩子项的行高 */
.VPSidebarItem.level-1 .text,
.VPSidebarItem.level-2 .text,
.VPSidebarItem.level-3 .text {
line-height: 1.4 !important;
padding: 0 !important; /* 移除文字本身的内边距 */
}
/* 强制链接本身没有额外的边距 */
.VPSidebarItem .VPLink {
padding-top: 2px !important;
padding-bottom: 2px !important;
min-height: auto !important;
}
/* 图片高度限制策略：根据长宽比调整最大高度 */
/* 越高的图片（长宽比越大），限制的高度越小，避免占用过多纵向空间 */
.vp-doc img.img-tall {
max-height: 450px !important;
width: auto !important;
}
.vp-doc img.img-very-tall {
max-height: 350px !important;
width: auto !important;
}
.vp-doc img.img-ultra-tall {
max-height: 250px !important;
width: auto !important;
}
/* Fix tagline wrapping issues */
.VPHomeHero .tagline {
white-space: nowrap;
max-width: none !important;
}