@wegic/blog

用于快速添加 Wegic Blog 组件到 React 项目的 CLI 工具。

特性

• 🚀 一键初始化博客配置
• 📦 自动安装所需依赖
• 🎨 完整的 Markdown 博客系统
• 💅 基于 Tailwind CSS 的精美样式
• 🔧 灵活的路径别名配置
• 📝 支持代码高亮和一键复制
• 📑 自动生成文章目录

安装

# 使用 pnpm
pnpm add -D @wegic/blog

# 使用 npm
npm install --save-dev @wegic/blog

# 使用 yarn
yarn add -D @wegic/blog

使用方法

一键初始化

在项目根目录运行:

npx wegic-blog init

或者直接运行:

npx wegic-blog

此命令会一次性完成所有设置:

• 创建 wegic-blog.json 配置文件
• 检查项目环境 (React, Vite, Tailwind CSS)
• 询问配置选项 (TypeScript, 路径别名等)
• 自动安装缺失的依赖包
• 自动复制所有博客组件到项目中

包含的组件

初始化后会自动添加以下所有组件:

页面组件

• BlogIndex - 博客列表页,展示所有文章
• BlogPost - 博客详情页,显示单篇文章内容
• PostCard - 文章卡片,用于列表展示

UI 组件

• MDRenderer - Markdown 渲染器
• CodeBlock - 代码块(支持语法高亮和复制)
• TableOfContents - 文章目录导航

Hooks

• useMarkdownRenderer - Markdown 渲染配置
• useToc - 目录生成
• useCodeBlock - 代码块功能

类型和工具

• types.ts - TypeScript 类型定义
• content.ts - 博客内容管理

样式

• prism-custom.css - 代码高亮样式

配置文件

初始化后会生成 wegic-blog.json:

{
  "$schema": "https://wegic.ai/schema/blog-config.json",
  "style": "default",
  "typescript": true,
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "src/index.css",
    "baseColor": "neutral"
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib",
    "hooks": "@/hooks",
    "pages": "@/pages"
  }
}

依赖要求

必需依赖

• React >= 18.0.0
• React DOM >= 18.0.0
• React Router >= 7.0.0

Markdown 相关

• react-markdown
• remark-gfm
• remark-frontmatter
• rehype-prism-plus
• rehype-slug
• rehype-autolink-headings
• rehype-external-links
• rehype-sanitize
• rehype-raw

样式

• Tailwind CSS >= 3.4.0
• @tailwindcss/typography (推荐)
• PostCSS
• Autoprefixer

项目结构

添加组件后,项目结构如下:

your-project/
├── src/
│   ├── components/
│   │   └── blog/
│   │       ├── BlogIndex.tsx      # 博客列表页
│   │       ├── BlogPost.tsx       # 博客详情页
│   │       ├── PostCard.tsx       # 文章卡片
│   │       ├── MDRenderer.tsx     # Markdown 渲染器
│   │       ├── CodeBlock.tsx      # 代码块组件
│   │       ├── TableOfContents.tsx # 目录组件
│   │       └── lib/
│   │           ├── types.ts       # 类型定义
│   │           └── content.ts     # 内容管理
│   ├── hooks/
│   │   └── blog/
│   │       ├── useMarkdownRenderer.tsx
│   │       ├── useToc.tsx
│   │       └── useCodeBlock.tsx
│   ├── styles/
│   │   └── prism-custom.css       # 代码高亮样式
│   └── blog/
│       ├── 2025-10-22-hello-world.md
│       └── 2025-10-23-react-tips.md
└── wegic-blog.json

快速开始

1. 安装和初始化

# 安装 CLI 工具
pnpm add -D @wegic/blog

# 初始化博客系统(自动安装所有组件)
npx wegic-blog init

2. 配置路由

在路由配置中添加博客路由:

import { BlogIndex } from '@/components/blog/BlogIndex';
import { BlogPost } from '@/components/blog/BlogPost';

const routes = [
  {
    path: '/blog',
    element: <BlogIndex />,
  },
  {
    path: '/blog/:slug',
    element: <BlogPost />,
  },
];

3. 创建博客文章

在 src/blog/ 目录下创建 Markdown 文件:

---
title: 我的第一篇博客
date: 2025-10-22
author: Your Name
excerpt: 这是文章摘要
tags: [React, TypeScript]
---

# 欢迎

这是文章内容...

\`\`\`typescript
const greeting = "Hello, World!";
console.log(greeting);
\`\`\`

4. 更新内容管理

编辑 src/components/blog/lib/content.ts,添加您的文章数据。

5. 启动开发服务器

npm run dev

访问 http://localhost:3000/blog 查看博客列表。

Tailwind CSS 配置

确保 tailwind.config.js 包含以下内容:

module.exports = {
  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {},
  },
  plugins: [require('@tailwindcss/typography')],
};

在 CSS 文件中导入 Tailwind 和 Prism 样式:

@tailwind base;
@tailwind components;
@tailwind utilities;

@import './styles/prism-custom.css';

故障排除

依赖安装失败

如果自动安装失败,可以手动安装:

pnpm add react-markdown remark-gfm remark-frontmatter rehype-prism-plus rehype-slug rehype-autolink-headings rehype-external-links rehype-sanitize rehype-raw

路径别名无法识别

确保 tsconfig.json 或 jsconfig.json 配置了路径别名:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Vite 配置:

import { defineConfig } from 'vite';
import path from 'path';

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
});

Tailwind 样式不生效

1. 确保安装了 Tailwind CSS 和相关依赖
2. 检查 tailwind.config.js 的 content 配置
3. 在主 CSS 文件中导入 Tailwind 指令
4. 重启开发服务器

示例项目

查看完整示例: wegic-blog-example

许可证

MIT

支持

如有问题或建议,请提交 issue: https://github.com/wegic/wegic-blog/issues