# Wilboerht's Blog

A personal blog built with VitePress, featuring bilingual support and modern development practices.

[English](#english) | [中文](#中文)

## English

### Overview

This is a modern, performant blog built with VitePress, supporting both English and Chinese content. It features a clean design, optimized performance, and comprehensive development tooling.

### Features

- 📝 Bilingual Support (English & Chinese)
- 🎨 Clean, Modern Design
- 🚀 VitePress-powered Static Site Generation
- 📱 Responsive Layout
- 🔍 SEO Optimized
- 🛠️ Comprehensive Development Tools
- 🔒 Security Best Practices

### Detailed Features

#### Content Management

- **Bilingual Content Structure**
  - Separate English (`/en`) and Chinese (`/zh`) content directories
  - Automatic language detection and switching
  - URL-based language routing

- **Post Management**
  - Markdown-based writing with enhanced syntax
  - Front matter support for metadata
  - Categories and tags support
  - Draft system for unpublished posts

- **Asset Management**
  - Automatic image optimization
  - Support for multiple media types (images, videos, PDFs)
  - Asset validation and broken link detection
  - Public assets directory for static files

#### Development Features

- **Modern Development Tools**
  - TypeScript support for type safety
  - ESLint for code linting
  - Prettier for code formatting
  - Husky for Git hooks
  - lint-staged for staged files checking

- **Testing Framework**
  - Vitest for unit testing
  - Coverage reporting
  - Visual test UI interface
  - Jest DOM testing utilities

- **Security Features**
  - NPM audit checks
  - Dependency updates monitoring
  - Security vulnerability scanning
  - Automated security checks

- **Performance Optimization**
  - Built-in performance monitoring
  - Image optimization tools
  - Caching strategies
  - Bundle size optimization

#### Quality Assurance

- **Documentation Validation**
  - Automated link checking
  - Asset verification
  - Documentation structure validation
  - Spell checking with custom dictionary

- **Code Quality**
  - Automated code style enforcement
  - Type checking
  - Dead code detection
  - Best practices enforcement

- **Continuous Integration**
  - Automated testing
  - Build verification
  - Security scanning
  - Performance benchmarking

#### Backup and Version Control

- **Automated Backup**
  - Scheduled content backups
  - Multiple backup locations support
  - Backup verification
  - Restore procedures

- **Version Control**
  - Conventional commit messages
  - Automated changelog generation
  - Semantic versioning
  - Release management

#### Development Scripts

```bash
# Content Development
npm run docs:dev          # Start development server
npm run docs:build        # Build for production
npm run docs:preview      # Preview production build
npm run docs:clean        # Clean build files
npm run docs:validate     # Validate documentation
npm run docs:validate-links # Validate links

# Quality Assurance
npm run verify           # Verify assets
npm run performance     # Monitor performance
npm run lint            # Check code style
npm run lint:fix        # Fix code style issues
npm run format          # Format code

# Security
npm run security:audit   # Run security audit
npm run security:check   # Check security issues
npm run security:full    # Full security scan

# Testing
npm run test            # Run tests
npm run test:coverage   # Generate coverage report

# Maintenance
npm run optimize-images # Optimize images
npm run backup         # Create backup
npm run changelog      # Generate changelog
npm run release        # Create new release
```

#### Directory Structure

```
.
├── docs/                    # Documentation and content
│   ├── .vitepress/         # VitePress configuration
│   │   ├── config.ts       # Main configuration
│   │   ├── theme/          # Custom theme
│   │   └── security-headers.ts # Security headers
│   ├── en/                 # English content
│   ├── zh/                 # Chinese content
│   ├── posts/              # Blog posts
│   └── public/             # Static assets
├── scripts/                # Utility scripts
│   ├── backup.js          # Backup utility
│   ├── optimize-images.js  # Image optimization
│   ├── performance-monitor.js # Performance monitoring
│   ├── security-check.js   # Security scanning
│   ├── validate-docs.js    # Documentation validation
│   ├── validate-links.js   # Link validation
│   └── verify-assets.js    # Asset verification
└── .vitepress/            # VitePress configuration
```

### Tech Stack

- VitePress v1.0.0-rc.40
- Vue 3
- TypeScript
- ESLint & Prettier
- Husky & lint-staged
- GitHub Actions CI/CD

### Quick Start / 快速开始

#### Using NPM Package / 使用 NPM 包

You can create a new blog using our npm package:

```bash
# Using npm
npm create @wilboerht/blog-template my-blog

# Using yarn
yarn create @wilboerht/blog-template my-blog

# Using pnpm
pnpm create @wilboerht/blog-template my-blog
```

The CLI will guide you through the setup process. After creation:

```bash
cd my-blog
npm install    # Install dependencies
npm run docs:dev  # Start development server
```

#### Manual Installation / 手动安装

If you prefer to clone the repository directly:

### Getting Started

1. Clone the repository:

```bash
git clone https://github.com/yourusername/your-blog.git
cd your-blog
```

2. Install dependencies:

```bash
npm install
```

3. Start development server:

```bash
npm run docs:dev
```

4. Build for production:

```bash
npm run docs:build
```

### Available Scripts

- `docs:dev` - Start development server
- `docs:build` - Build for production
- `docs:preview` - Preview production build
- `lint` - Check code style (JS & Vue files)
- `lint:fix` - Fix code style issues
- `format` - Format code with Prettier
- `optimize-images` - Optimize images in docs directory
- `backup` - Create backup of docs directory
- `test` - Run tests
- `security:check` - Run security checks

### Project Structure

```
.
├── docs/                 # Documentation source files
│   ├── en/              # English content
│   ├── zh/              # Chinese content
│   └── public/          # Static assets
├── .vitepress/          # VitePress configuration
├── scripts/             # Utility scripts
└── .github/             # GitHub configurations
```

### Contributing

Please read our [Contributing Guide](./CONTRIBUTING.md) before making a contribution.

### Troubleshooting Guide

#### Common Issues and Solutions

##### 1. Node.js Version Issues

**Problem**: Build fails or dependencies don't install correctly
**Solution**: 
- Ensure you're using Node.js version 16 or higher
- Try removing `node_modules` and `package-lock.json`, then run `npm install` again

```bash
rm -rf node_modules package-lock.json
npm install
```

##### 2. Build Errors

**Problem**: VitePress build fails
**Solution**:
- Check for syntax errors in Markdown files
- Ensure all images have correct paths
- Clear the cache and rebuild:

```bash
npm run docs:clean # if available
npm run docs:build
```

##### 3. Content Not Updating

**Problem**: Changes not reflecting in development server
**Solution**:
- Stop the development server
- Clear your browser cache
- Restart the development server with:

```bash
npm run docs:dev
```

##### 4. Image Loading Issues

**Problem**: Images not displaying correctly
**Solution**:
- Verify image paths are relative to the markdown file
- Ensure images are in the correct public directory
- Use the correct image format (supported: .jpg, .png, .gif, .svg)

##### 5. Deployment Issues

**Problem**: Site not deploying correctly
**Solution**:
- Check your base URL configuration in `.vitepress/config.ts`
- Verify GitHub Actions workflow is running correctly
- Ensure all dependencies are properly listed in `package.json`

##### 6. Style Issues

**Problem**: Custom styles not applying
**Solution**:
- Check if your custom CSS is properly imported
- Verify the CSS selectors are correct
- Clear browser cache and refresh

##### 7. Performance Issues

**Problem**: Site loading slowly
**Solution**:
- Optimize image sizes
- Minimize JavaScript bundles
- Enable gzip compression on your server
- Use the built-in image optimization:

```bash
npm run optimize-images
```

#### Getting Help

If you encounter any other issues:

1. Check the [VitePress documentation](https://vitepress.dev/)
2. Search for similar issues in the project's issue tracker
3. Create a new issue with:
   - Detailed description of the problem
   - Steps to reproduce
   - Error messages
   - Environment information (OS, Node.js version, npm version)

## 中文

### 概述

这是一个使用 VitePress 构建的现代化博客，支持中英双语内容。它具有清晰的设计、优化的性能和完整的开发工具链。

### 特性

- 📝 双语支持（中文和英文）
- 🎨 清晰现代的设计
- 🚀 VitePress 驱动的静态站点生成
- 📱 响应式布局
- 🔍 SEO 优化
- 🛠️ 完整的开发工具
- 🔒 安全最佳实践

### 详细功能

#### 内容管理

- **双语内容结构**
  - 单独的英文 (`/en`) 和中文 (`/zh`) 内容目录
  - 自动语言检测和切换
  - 基于 URL 的语言路由

- **文章管理**
  - 基于 Markdown 的写作，增强语法
  - 前置元数据支持
  - 分类和标签支持
  - 草稿系统

- **资源管理**
  - 自动图像优化
  - 支持多种媒体类型（图像、视频、PDF）
  - 资源验证和断链检测
  - 公共资源目录

#### 开发功能

- **现代开发工具**
  - TypeScript 支持类型安全
  - ESLint 代码检查
  - Prettier 代码格式化
  - Husky Git 钩子
  - lint-staged 阶段文件检查

- **测试框架**
  - Vitest 单元测试
  - 覆盖率报告
  - 测试 UI 界面
  - Jest DOM 测试工具

- **安全功能**
  - NPM 审计检查
  - 依赖更新监控
  - 安全漏洞扫描
  - 自动安全检查

- **性能优化**
  - 内置性能监控
  - 图像优化工具
  - 缓存策略
  - 包大小优化

#### 质量保证

- **文档验证**
  - 自动链接检查
  - 资源验证
  - 文档结构验证
  - 拼写检查

- **代码质量**
  - 自动代码风格强制
  - 类型检查
  - 死代码检测
  - 最佳实践强制

- **持续集成**
  - 自动测试
  - 构建验证
  - 安全扫描
  - 性能基准测试

#### 备份和版本控制

- **自动备份**
  - 定期内容备份
  - 多个备份位置支持
  - 备份验证
  - 恢复程序

- **版本控制**
  - 规范化提交消息
  - 自动更新日志生成
  - 语义化版本控制
  - 发布管理

#### 开发脚本

```bash
# 内容开发
npm run docs:dev          # 启动开发服务器
npm run docs:build        # 构建生产版本
npm run docs:preview      # 预览生产构建
npm run docs:clean        # 清理构建文件
npm run docs:validate     # 验证文档
npm run docs:validate-links # 验证链接

# 质量保证
npm run verify           # 验证资源
npm run performance     # 监控性能
npm run lint            # 检查代码风格
npm run lint:fix        # 修复代码风格问题
npm run format          # 格式化代码

# 安全
npm run security:audit   # 运行安全审计
npm run security:check   # 检查安全问题
npm run security:full    # 完整安全扫描

# 测试
npm run test            # 运行测试
npm run test:coverage   # 生成覆盖率报告

# 维护
npm run optimize-images # 优化图像
npm run backup         # 创建备份
npm run changelog      # 生成更新日志
npm run release        # 创建新版本
```

#### 目录结构

```
.
├── docs/                    # 文档和内容
│   ├── .vitepress/         # VitePress 配置
│   │   ├── config.ts       # 主配置文件
│   │   ├── theme/          # 自定义主题
│   │   └── security-headers.ts # 安全头配置
│   ├── en/                 # 英文内容
│   ├── zh/                 # 中文内容
│   ├── posts/              # 博客文章
│   └── public/             # 静态资源
├── scripts/                # 实用脚本
│   ├── backup.js          # 备份工具
│   ├── optimize-images.js  # 图像优化
│   ├── performance-monitor.js # 性能监控
│   ├── security-check.js   # 安全扫描
│   ├── validate-docs.js    # 文档验证
│   ├── validate-links.js   # 链接验证
│   └── verify-assets.js    # 资源验证
└── .vitepress/            # VitePress 配置
```

### 开始使用

1. 克隆仓库：

```bash
git clone https://github.com/yourusername/your-blog.git
cd your-blog
```

2. 安装依赖：

```bash
npm install
```

3. 启动开发服务器：

```bash
npm run docs:dev
```

4. 构建生产版本：

```bash
npm run docs:build
```

### 可用脚本

- `docs:dev` - 启动开发服务器
- `docs:build` - 构建生产版本
- `docs:preview` - 预览生产构建
- `lint` - 检查代码风格（JS 和 Vue 文件）
- `lint:fix` - 修复代码风格问题
- `format` - 格式化代码
- `optimize-images` - 优化图像
- `backup` - 创建备份
- `test` - 运行测试
- `security:check` - 运行安全检查

### 项目结构

```
.
├── docs/                 # 文档源文件
│   ├── en/              # 英文内容
│   ├── zh/              # 中文内容
│   └── public/          # 静态资源
├── .vitepress/          # VitePress 配置
├── scripts/             # 实用脚本
└── .github/             # GitHub 配置
```

### 贡献

在提交贡献之前，请阅读我们的[贡献指南](./CONTRIBUTING.md)。

### 故障排除指南

#### 常见问题及解决方案

##### 1. Node.js 版本问题

**问题**: 构建失败或依赖项未正确安装
**解决方案**:
- 确保您使用的是 Node.js 版本 16 或更高版本
- 尝试删除 `node_modules` 和 `package-lock.json`，然后运行 `npm install` 再次安装

```bash
rm -rf node_modules package-lock.json
npm install
```

##### 2. 构建错误

**问题**: VitePress 构建失败
**解决方案**:
- 检查 Markdown 文件中的语法错误
- 确保所有图片路径正确
- 清除缓存并重新构建：

```bash
npm run docs:clean # 如果可用
npm run docs:build
```

##### 3. 内容未更新

**问题**: 更改未反映在开发服务器中
**解决方案**:
- 停止开发服务器
- 清除浏览器缓存
- 重新启动开发服务器：

```bash
npm run docs:dev
```

##### 4. 图片加载问题

**问题**: 图片未正确显示
**解决方案**:
- 验证图片路径是否相对于 Markdown 文件
- 确保图片位于正确的公共目录中
- 使用正确的图片格式（支持：.jpg、.png、.gif、.svg）

##### 5. 部署问题

**问题**: 网站未正确部署
**解决方案**:
- 检查 `.vitepress/config.ts` 中的基本 URL 配置
- 验证 GitHub Actions 工作流是否正确运行
- 确保所有依赖项都正确列在 `package.json` 中

##### 6. 样式问题

**问题**: 自定义样式未应用
**解决方案**:
- 检查自定义 CSS 是否正确导入
- 验证 CSS 选择器是否正确
- 清除浏览器缓存并刷新

##### 7. 性能问题

**问题**: 网站加载缓慢
**解决方案**:
- 优化图片大小
- 最小化 JavaScript 包
- 在服务器上启用 gzip 压缩
- 使用内置的图片优化：

```bash
npm run optimize-images
```

#### 获取帮助

如果您遇到其他问题：

1. 检查 [VitePress 文档](https://vitepress.dev/)
2. 在项目的 issue 跟踪器中搜索类似的问题
3. 创建一个新问题，包括：
   - 详细描述问题
   - 重现步骤
   - 错误消息
   - 环境信息（操作系统、Node.js 版本、npm 版本）

## License

MIT License - see the [LICENSE](./LICENSE) file for details.