利用Vue和VitePress从零搭建Markdown文档网站的完整教程，包含基础配置、自定义组件、样式美化和部署上线。

kkcode
kkcode
2026-02-13阅读 1102

以下是从零搭建 Vue + VitePress Markdown 文档网站的完整教程，包含基础配置、自定义组件、样式美化和部署上线。
在线体验站点：https://xdai.fun/docs/

一、环境准备

VitePress 依赖 Node.js（推荐 v16.0.0+），先检查/安装环境：

  1. 检查 Node 版本： 
    node -v # 输出 >=16.0.0 即可
  2. 推荐使用 pnpm 包管理器（也可用 npm/yarn）： 
    npm install -g pnpm

二、初始化项目

1. 创建项目目录并初始化

# 创建文件夹
mkdir vitepress-docs && cd vitepress-docs
# 初始化 package.json
pnpm init -y
# 安装 VitePress 依赖
pnpm add -D vitepress

2. 初始化文档目录结构

VitePress 的核心目录约定：

vitepress-docs/
├── docs/                # 文档根目录
│   ├── .vitepress/      # 配置目录（自动生成）
│   │   ├── config.js    # 核心配置文件
│   │   ├── components/  # 自定义 Vue 组件
│   │   └── style.css    # 自定义样式
│   ├── guide/           # 文档子目录（示例）
│   │   ├── quick-start.md
│   │   └── config.md
│   └── index.md         # 首页文档
└── package.json         # 项目配置

手动创建基础文件：

# 创建 docs 目录和首页
mkdir docs && echo '# Hello VitePress' > docs/index.md

3. 配置 npm 脚本

修改 package.json，添加开发/构建/预览脚本：

{
  "name": "vitepress-docs",
  "version": "1.0.0",
  "scripts": {
    "docs:dev": "vitepress dev docs",    // 本地开发
    "docs:build": "vitepress build docs",// 构建静态文件
    "docs:preview": "vitepress preview docs" // 预览构建结果
  },
  "devDependencies": {
    "vitepress": "^1.0.0"
  }
}

三、基础配置（核心）

创建 docs/.vitepress/config.js（VitePress 核心配置文件），配置网站标题、导航、侧边栏等：

export default {
  // 站点基础配置
  title: "我的文档网站",        // 网站标题（浏览器标签）
  description: "基于 VitePress 搭建的 Vue 文档站", // SEO 描述
  base: "/vitepress-docs/",     // 部署基础路径（GitHub Pages 需填仓库名）
  lang: "zh-CN",                // 语言

  // 主题配置（导航、侧边栏、社交链接等）
  themeConfig: {
    // 导航栏
    nav: [
      { text: "首页", link: "/" },
      { text: "指南", link: "/guide/quick-start" },
      { text: "GitHub", link: "https://github.com" },
    ],

    // 侧边栏（按路径分组）
    sidebar: {
      "/guide/": [
        {
          text: "基础指南", // 分组标题
          collapsible: true, // 是否可折叠
          items: [
            { text: "快速开始", link: "/guide/quick-start" },
            { text: "配置说明", link: "/guide/config" },
          ],
        },
      ],
    },

    // 社交链接（内置图标：github、twitter 等）
    socialLinks: [{ icon: "github", link: "https://github.com" }],

    // 页脚
    footer: {
      message: "Released under the MIT License.",
      copyright: "Copyright © 2024-present Your Name",
    },

    // 编辑链接（点击文档右上角“编辑”跳转）
    editLink: {
      pattern: "https://github.com/你的用户名/vitepress-docs/edit/main/docs/:path",
      text: "在 GitHub 上编辑此页",
    },
  },
};

四、编写文档内容

1. 自定义首页（美化）

替换 docs/index.md，使用 VitePress 内置的 home 布局：

---
layout: home # 启用首页布局
hero:
  name: "我的文档站"
  text: "基于 VitePress + Vue 构建"
  tagline: 轻量、高效、易扩展的文档解决方案
  actions:
    - theme: brand # 主按钮
      text: 快速开始
      link: /guide/quick-start
    - theme: alt # 次要按钮
      text: 查看源码
      link: https://github.com
features:
  - title: 极速构建
    details: 基于 Vite 驱动，热更新秒级响应，构建速度远超传统工具
  - title: Vue 原生支持
    details: Markdown 中可直接使用 Vue 组件，无缝集成 Vue 生态
  - title: 自定义主题
    details: 灵活的主题配置，支持自定义样式、组件和布局
---

2. 编写子文档

创建 docs/guide/quick-start.md，内容如下：

# 快速开始

## 1. 环境准备
确保安装 Node.js >=16.0.0，推荐使用 pnpm 包管理器：
npm install -g pnpm

## 2. 启动开发服务
pnpm docs:dev

## 3. 构建生产版本
pnpm docs:build

创建 docs/guide/config.md（可补充配置说明），内容如下：

# 配置说明

VitePress 的核心配置文件是 `.vitepress/config.js`，主要包含：
- 站点基础配置（title、base、lang）
- 主题配置（nav、sidebar、footer）
- 构建配置（outDir、assetsDir）

五、本地运行

执行以下命令启动开发服务器：

pnpm docs:dev

访问 http://localhost:5173 即可看到文档网站，修改 Markdown 或配置会实时热更新。

六、进阶：自定义 Vue 组件

VitePress 支持在 Markdown 中直接使用 Vue 组件，步骤如下：

1. 创建自定义组件

新建 docs/.vitepress/components/Hello.vue：

<template>
  <div class="hello-component">
    <h3>{{ msg }}</h3>
    <p>这是一个 Vue 组件，可直接在 Markdown 中使用！</p>
  </div>
</template>

<script setup>
const msg = "Hello Vue + VitePress!";
</script>

<style scoped>
.hello-component {
  padding: 16px;
  border: 1px solid #42b983;
  border-radius: 8px;
  margin: 16px 0;
  color: #333;
}
</style>

2. 在 Markdown 中使用组件

修改 docs/guide/quick-start.md，直接引入组件（无需注册）：

# 快速开始

<Hello />

## 1. 环境准备
确保安装 Node.js >=16.0.0，推荐使用 pnpm 包管理器：
npm install -g pnpm

## 2. 启动开发服务
pnpm docs:dev

## 3. 构建生产版本
pnpm docs:build

七、自定义样式

创建 docs/.vitepress/style.css，覆盖 VitePress 内置样式：

/* 自定义主题色 */
:root {
  --vp-c-brand: #646cff;       /* 主色 */
  --vp-c-brand-light: #747bff; /* 浅色 */
  --vp-c-brand-dark: #535bf2;  /* 深色 */
}

/* 自定义文档内边距 */
.VPContent {
  padding: 20px 0;
}

/* 自定义代码块样式 */
div[class*="language-"] pre {
  border-radius: 8px;
}

八、构建与部署（GitHub Pages）

1. 安装部署依赖

pnpm add -D gh-pages

2. 添加部署脚本

修改 package.json：

"scripts": {
  "docs:dev": "vitepress dev docs",
  "docs:build": "vitepress build docs",
  "docs:preview": "vitepress preview docs",
  "docs:deploy": "pnpm docs:build && gh-pages -d docs/.vitepress/dist"
}

3. 部署到 GitHub Pages

  1. 在 GitHub 创建仓库（例如 vitepress-docs）；
  2. 本地关联仓库： 
    git init
git remote add origin https://github.com/你的用户名/vitepress-docs.git
  3. 执行部署命令： 
    pnpm docs:deploy
  4. 打开 GitHub 仓库 → Settings → Pages，即可看到部署后的地址（通常是 https://你的用户名.github.io/vitepress-docs/）。

九、核心特性补充

  1. Markdown 增强：VitePress 支持表格、任务列表、代码高亮、数学公式等扩展语法；
  2. 暗黑模式：内置暗黑模式，可通过 themeConfig.darkMode = true 开启；
  3. 搜索功能：内置本地搜索，无需额外配置；
  4. 多语言：支持配置多语言文档（参考 VitePress 多语言文档）；
  5. 插件扩展：可通过 config.js 的 plugins 配置第三方插件（如图表、看板等）。

常见问题

  • 资源加载失败：检查 config.js 中的 base 路径是否与 GitHub 仓库名一致；
  • 组件不渲染：确保组件放在 .vitepress/components 目录下，且命名符合 Vue 组件规范；
  • Node 版本过低：升级 Node 到 v16+，或使用 nvm 管理版本。

参考文档

本文链接: http://qdgithub.com:443/article/2051
评论数量：0