@wilboerht/blog-template

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