1.0.0 • Published 7 months ago

@wilboerht/blog-template v1.0.0

Weekly downloads
-
License
MIT
Repository
github
Last release
7 months ago

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
  1. Install dependencies:
npm install
  1. Start development server:
npm run docs:dev
  1. 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
  1. 安装依赖：
npm install
  1. 启动开发服务器：
npm run docs:dev
  1. 构建生产版本：
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.

blogvitepressvuetechprogrammingpersonal-blogbilingualblog-templatestatic-sitemarkdown
@vueuse/corechalkcommanderfs-extramarkdown-it-anchorpromptsvitepressvue
1.0.0

7 months ago