VitePress 学习指南

主题

迁移专题指南 ​

本文档介绍如何从其他静态站点生成工具迁移到 VitePress。

📊 迁移概览 ​

来源工具迁移难度主要变更预计时间
VuePress⭐ 简单配置格式相似1-2 小时
Docusaurus⭐⭐ 中等React → Vue1-3 天
Docsify⭐⭐ 中等无构建 → 有构建2-4 小时
Hexo⭐⭐⭐ 较难模板系统不同1-2 天
Hugo⭐⭐⭐ 较难Go 模板 → Vue2-3 天
Jekyll⭐⭐⭐ 较难Ruby → Node.js1-2 天

从 Docusaurus 迁移 ​

概述 ​

Docusaurus 是 Facebook 开发的文档工具，基于 React。迁移到 VitePress 需要处理 React 到 Vue 的转换。

目录结构对比 ​

bash
# Docusaurus
my-website/
├── docs/
├── blog/
├── src/
│   ├── pages/
│   ├── components/
│   └── css/
├── static/
└── docusaurus.config.js

# VitePress
my-website/
├── docs/
│   ├── guide/
│   ├── blog/
│   ├── public/
│   └── .vitepress/
│       ├── config.mts
│       └── theme/
└── package.json

配置迁移 ​

javascript
// docusaurus.config.js
module.exports = {
  title: 'My Site',
  tagline: 'Site tagline',
  url: 'https://example.com',
  baseUrl: '/',
  
  themeConfig: {
    navbar: {
      title: 'My Site',
      logo: { src: 'img/logo.svg' },
      items: [
        { to: '/docs/', label: 'Docs', position: 'left' }
      ]
    },
    footer: {
      style: 'dark',
      links: [...]
    }
  }
}

转换为 VitePress：

ts
// docs/.vitepress/config.mts
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'My Site',
  description: 'Site tagline',
  base: '/',
  
  themeConfig: {
    logo: '/img/logo.svg',
    nav: [
      { text: 'Docs', link: '/guide/' }
    ],
    footer: {
      message: 'Site footer message',
      copyright: 'Copyright © 2024'
    }
  }
})

组件迁移 ​

Docusaurus (React) → VitePress (Vue)：

jsx
// Docusaurus React 组件
import React from 'react';

export default function MyComponent({ title }) {
  return (
    <div className="my-component">
      <h2>{title}</h2>
      <p>Content here</p>
    </div>
  );
}

转换为 Vue：

vue
<!-- VitePress Vue 组件 -->
<script setup>
defineProps({
  title: String
})
</script>

<template>
  <div class="my-component">
    <h2>{{ title }}</h2>
    <p>Content here</p>
  </div>
</template>

Markdown 特性 ​

特性DocusaurusVitePress
代码块```` jsx ```` js
Admonitions:::tip::: tip
Tabs<Tabs>::: code-group
TOC## 目录 {Preamble}[[toc]]

迁移脚本 ​

bash
#!/bin/bash
# migrate-from-docusaurus.sh

# 创建目标目录
mkdir -p docs/.vitepress/theme

# 移动文档
mv docs/* docs/guide/ 2>/dev/null || true

# 移动静态资源
mv static/* docs/public/ 2>/dev/null || true

# 转换组件（需要手动）
echo "请手动将 React 组件转换为 Vue 组件"

echo "基础迁移完成！"

从 Docsify 迁移 ​

概述 ​

Docsify 是无构建的文档工具，直接在浏览器中渲染 Markdown。迁移到 VitePress 需要添加构建流程。

目录结构对比 ​

bash
# Docsify
docs/
├── index.html
├── README.md
├── guide/
│   └── README.md
├── _sidebar.md
├── _navbar.md
└── _coverpage.md

# VitePress
docs/
├── index.md
├── guide/
│   └── index.md
└── .vitepress/
    └── config.mts

配置迁移 ​

html
<!-- Docsify index.html -->
<script>
  window.$docsify = {
    name: 'My Docs',
    repo: 'user/repo',
    loadSidebar: '_sidebar',
    loadNavbar: '_navbar',
    coverpage: '_coverpage',
    subMaxLevel: 2
  }
</script>

转换为 VitePress：

ts
// docs/.vitepress/config.mts
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'My Docs',
  
  themeConfig: {
    socialLinks: [
      { icon: 'github', link: 'https://github.com/user/repo' }
    ],
    sidebar: {
      '/guide/': [
        {
          text: '指南',
          items: [
            { text: '介绍', link: '/guide/' }
          ]
        }
      ]
    },
    outline: {
      level: [2, 3]
    }
  }
})

侧边栏迁移 ​

markdown
<!-- Docsify _sidebar.md -->
- [介绍](/)
- [指南](/guide/)
  - [快速开始](/guide/quickstart)
  - [配置](/guide/config)

转换为 VitePress 配置：

ts
// docs/.vitepress/config.mts
export default defineConfig({
  themeConfig: {
    sidebar: [
      {
        text: '介绍',
        link: '/'
      },
      {
        text: '指南',
        items: [
          { text: '快速开始', link: '/guide/quickstart' },
          { text: '配置', link: '/guide/config' }
        ]
      }
    ]
  }
})

封面页迁移 ​

markdown
<!-- Docsify _coverpage.md -->
# My Docs

> 一个神奇的文档站点

[Get Started](#guide)

转换为 VitePress 首页：

markdown
<!-- docs/index.md -->
---
layout: home
hero:
  name: My Docs
  text: 文档站点
  tagline: 一个神奇的文档站点
  actions:
    - theme: brand
      text: 开始使用
      link: /guide/
---

插件迁移 ​

Docsify 插件VitePress 替代方案
docsify-plugin-codefund自定义广告组件
docsify-copy-code内置代码复制
docsify-paginationDocFooter 组件
docsify-search内置本地搜索
docsify-tabs::: code-group

迁移步骤 ​

bash
#!/bin/bash
# migrate-from-docsify.sh

# 1. 初始化 VitePress
mkdir -p docs/.vitepress/theme
touch docs/.vitepress/config.mts

# 2. 重命名文件
mv docs/README.md docs/index.md
find docs -name "README.md" -exec sh -c 'mv "$1" "${1%/*}/index.md"' _ {} \;

# 3. 移除 Docsify 特定文件
rm docs/index.html
rm docs/_sidebar.md
rm docs/_navbar.md
rm docs/_coverpage.md

echo "迁移完成！请手动配置 config.mts"

从 Hexo 迁移 ​

概述 ​

Hexo 是流行的博客框架，使用 EJS/Swig 模板。迁移到 VitePress 主要涉及模板转换。

目录结构对比 ​

bash
# Hexo
blog/
├── source/
│   ├── _posts/
│   └── _drafts/
├── themes/
├── scaffolds/
├── _config.yml
└── package.json

# VitePress
blog/
├── docs/
│   ├── posts/
│   └── .vitepress/
│       ├── config.mts
│       └── theme/
└── package.json

配置迁移 ​

yaml
# Hexo _config.yml
title: My Blog
subtitle: Blog subtitle
description: Blog description
author: Author Name
url: https://example.com

theme_config:
  nav:
    - name: Home
      link: /
    - name: Archives
      link: /archives

转换为 VitePress：

ts
// docs/.vitepress/config.mts
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'My Blog',
  description: 'Blog description',
  
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Archives', link: '/archives' }
    ]
  }
})

文章迁移 ​

Hexo 文章：

markdown
---
title: Hello World
date: 2024-01-01 10:00:00
tags: [javascript, vue]
categories: frontend
---

文章内容...

转换为 VitePress：

markdown
---
title: Hello World
date: 2024-01-01
tags:
  - JavaScript
  - Vue
category: frontend
---

文章内容...

迁移脚本 ​

bash
#!/bin/bash
# migrate-from-hexo.sh

# 创建目标目录
mkdir -p docs/posts

# 移动文章
cp -r source/_posts/* docs/posts/

# 转换 frontmatter（简化版）
for file in docs/posts/*.md; do
  # 修改日期格式
  sed -i "s/date: \([0-9-]*\) [0-9:]*$/date: \1/" "$file"
  
  # 转换标签格式
  sed -i "s/tags: \[\(.*\)\]/tags:\n  - \1/" "$file"
done

# 创建归档页面
touch docs/archives.md

echo "文章迁移完成！"

从 Hugo 迁移 ​

概述 ​

Hugo 是 Go 语言编写的静态站点生成器，使用 Go 模板。迁移需要将模板转换为 Vue。

目录结构对比 ​

bash
# Hugo
site/
├── content/
│   ├── posts/
│   └── _index.md
├── layouts/
├── static/
├── themes/
└── config.toml

# VitePress
site/
├── docs/
│   ├── posts/
│   ├── index.md
│   ├── public/
│   └── .vitepress/
│       ├── config.mts
│       └── theme/
└── package.json

配置迁移 ​

toml
# Hugo config.toml
baseURL = "https://example.com/"
title = "My Site"
theme = "my-theme"

[menu]
  [[menu.main]]
    name = "Home"
    url = "/"
    weight = 1

转换为 VitePress：

ts
// docs/.vitepress/config.mts
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'My Site',
  base: '/',
  
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' }
    ]
  }
})

内容迁移 ​

Hugo 的 shortcodes 需要转换为 Vue 组件：

markdown
<!-- Hugo shortcode -->
{{< youtube video_id >}}

转换为 VitePress 组件：

vue
<!-- docs/.vitepress/theme/components/YouTube.vue -->
<script setup>
defineProps({
  id: String
})
</script>

<template>
  <iframe 
    :src="`https://www.youtube.com/embed/${id}`"
    width="560"
    height="315"
    frameborder="0"
    allowfullscreen
  />
</template>

从 Jekyll 迁移 ​

概述 ​

Jekyll 是 Ruby 编写的静态站点生成器，使用 Liquid 模板。

目录结构对比 ​

bash
# Jekyll
site/
├── _posts/
├── _layouts/
├── _includes/
├── _config.yml
└── index.html

# VitePress
site/
├── docs/
│   ├── posts/
│   ├── index.md
│   └── .vitepress/
│       ├── config.mts
│       └── theme/
└── package.json

配置迁移 ​

yaml
# Jekyll _config.yml
title: My Site
description: Site description
url: "https://example.com"

navigation:
  - title: Home
    url: /
  - title: About
    url: /about

转换为 VitePress：

ts
// docs/.vitepress/config.mts
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'My Site',
  description: 'Site description',
  
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'About', link: '/about' }
    ]
  }
})

Liquid 模板迁移 ​

liquid
<!-- Jekyll Liquid -->
{% for post in site.posts %}
  <h2>{{ post.title }}</h2>
{% endfor %}

转换为 Vue：

vue
<script setup>
import { data as posts } from './posts.data'
</script>

<template>
  <article v-for="post in posts" :key="post.url">
    <h2>
      <a :href="post.url">{{ post.title }}</a>
    </h2>
  </article>
</template>

通用迁移步骤 ​

1. 准备工作 ​

bash
# 创建新项目
mkdir my-vitepress-site
cd my-vitepress-site

# 初始化
npm init -y

# 安装 VitePress
npm add -D vitepress

# 创建目录结构
mkdir -p docs/.vitepress/theme
touch docs/.vitepress/config.mts
touch docs/index.md

2. 内容迁移 ​

bash
# 复制 Markdown 文件
cp -r old-project/docs/* docs/

# 重命名首页
mv docs/README.md docs/index.md 2>/dev/null || true

# 移动静态资源
mv old-project/static/* docs/public/ 2>/dev/null || true

3. 配置迁移 ​

手动将原配置转换为 VitePress 格式：

  • 导航栏 → themeConfig.nav
  • 侧边栏 → themeConfig.sidebar
  • 全局配置 → 顶层配置

4. 组件迁移 ​

将原有组件转换为 Vue 组件：

  • React 组件 → Vue SFC
  • Liquid/EJS 模板 → Vue 模板
  • Shortcodes → Vue 组件

5. 测试验证 ​

bash
# 启动开发服务器
npm run docs:dev

# 构建测试
npm run docs:build

# 预览构建结果
npm run docs:preview

迁移检查清单 ​

  • [ ] 安装 VitePress 依赖
  • [ ] 创建目录结构
  • [ ] 迁移 Markdown 内容
  • [ ] 迁移静态资源
  • [ ] 转换配置文件
  • [ ] 转换组件
  • [ ] 配置导航栏
  • [ ] 配置侧边栏
  • [ ] 测试所有链接
  • [ ] 检查样式
  • [ ] 配置部署

下一步 ​

完成迁移后，你可以：

贡献者

加载中...

想要成为贡献者？

在 CNB 上参与贡献

Copyright © 2016 - 2026 VitePress 学习指南