Wilboerht's Blog

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

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

# 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:

# 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:

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:

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

2. Install dependencies:

npm install

3. Start development server:

npm run docs:dev

4. Build for production:

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 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

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:

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:

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:

npm run optimize-images

Getting Help

If you encounter any other issues:

1. Check the VitePress documentation
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 审计检查
  • 依赖更新监控
  • 安全漏洞扫描
  • 自动安全检查

• 性能优化

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

质量保证

• 文档验证

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

• 代码质量

  • 自动代码风格强制
  • 类型检查
  • 死代码检测
  • 最佳实践强制

• 持续集成

  • 自动测试
  • 构建验证
  • 安全扫描
  • 性能基准测试

备份和版本控制

• 自动备份

  • 定期内容备份
  • 多个备份位置支持
  • 备份验证
  • 恢复程序

• 版本控制

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

开发脚本

# 内容开发
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. 克隆仓库：

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

2. 安装依赖：

npm install

3. 启动开发服务器：

npm run docs:dev

4. 构建生产版本：

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 配置

贡献

在提交贡献之前，请阅读我们的贡献指南。

故障排除指南

常见问题及解决方案

1. Node.js 版本问题

问题: 构建失败或依赖项未正确安装 解决方案:

• 确保您使用的是 Node.js 版本 16 或更高版本
• 尝试删除 node_modules 和 package-lock.json，然后运行 npm install 再次安装

rm -rf node_modules package-lock.json
npm install

2. 构建错误

问题: VitePress 构建失败 解决方案:

• 检查 Markdown 文件中的语法错误
• 确保所有图片路径正确
• 清除缓存并重新构建：

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

3. 内容未更新

问题: 更改未反映在开发服务器中 解决方案:

• 停止开发服务器
• 清除浏览器缓存
• 重新启动开发服务器：

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 压缩
• 使用内置的图片优化：

npm run optimize-images

获取帮助

如果您遇到其他问题：

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

License

MIT License - see the LICENSE file for details.