diff --git a/CLAUDE.md b/CLAUDE.md index 19fd595..a63ef3b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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,21 +41,31 @@ 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) -│ ├── 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 -│ ├── extra/ # Additional knowledge (Git, API, RAG, etc.) -│ └── project/ # Legacy project documentation -├── assets/ # Images and static assets (symlinked in docs/) -├── package.json # Project dependencies and scripts -└── README.md # Project overview and contribution guide +├── 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 (legacy) +│ ├── extra/ # Additional knowledge (Git, API, RAG, etc.) +│ ├── guide/ # Course guide +│ └── project/ # Legacy project documentation +├── assets/ # Images and static assets +├── package.json # Project dependencies and scripts +├── vercel.json # Vercel deployment configuration +└── README.md # Project overview and contribution guide ``` ### Content Organization @@ -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) diff --git a/docs/.vitepress/theme/index.js b/docs/.vitepress/theme/index.js index 2c7c5e4..dcff46d 100644 --- a/docs/.vitepress/theme/index.js +++ b/docs/.vitepress/theme/index.js @@ -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, diff --git a/docs/public/style.css b/docs/public/style.css new file mode 100644 index 0000000..918fbe0 --- /dev/null +++ b/docs/public/style.css @@ -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; +}