介绍

VuePress 是一个以 Markdown 为中心的静态网站生成器。你可以使用 Markdown在新窗口打开 来书写内容（如文档、博客等），然后 VuePress 会帮助你生成一个静态网站来展示它们。

VuePress 诞生的初衷是为了支持 Vue.js 及其子项目的文档需求，但是现在它已经在帮助大量用户构建他们的文档、博客和其他静态网站。

项目地址：https://vuepress.vuejs.org/zh/

项目手册：https://vuepress.vuejs.org/zh/guide/getting-started.html

安装

依赖环境

• Node.js v18.16.0+
• 包管理器，如 pnpm、yarn、npm 等。

使用 pnpm时，你需要安装 vue 作为 peer-dependencies 。

使用 yarn 2+时，你需要在 .yarnrc.yml 文件中设置 nodeLinker: 'node-modules' 。

创建项目

通过命令行创建

你可以通过 create-vuepress 直接创建项目模板

pnpm create vuepress vuepress-starter

手动创建

• 创建并进入一个新目录

mkdir vuepress-starter
cd vuepress-starter

• 初始化项目

git init
pnpm init

• 安装 VuePress

# 安装 vuepress 和 vue
pnpm add -D vuepress@next vue
# 安装打包工具和主题
pnpm add -D @vuepress/bundler-vite@next @vuepress/theme-default@next

• 创建 docs 目录和 docs/.vuepress 目录

mkdir docs
mkdir docs/.vuepress

• 创建 VuePress 配置文件 docs/.vuepress/config.js

import { viteBundler } from '@vuepress/bundler-vite'
import { defaultTheme } from '@vuepress/theme-default'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  bundler: viteBundler(),
  theme: defaultTheme(),
})

• 创建你的第一篇文档

echo '# Hello VuePress' > docs/README.md

目录结构

创建完成后，你项目的目录结构应该是这样的：

├─ docs
│ ├─ .vuepress
│ │ └─ config.js
│ └─ README.md
└─ package.json

docs 目录是你放置 Markdown 文件的地方，它同时也会作为 VuePress 的源文件目录。

docs/.vuepress 目录，即源文件目录下的 .vuepress 目录，是放置所有和 VuePress 相关的文件的地方。当前这里只有一个配置文件。默认还会在该目录下生成临时文件、缓存文件和构建输出文件。建议你把它们添加到 .gitignore 文件中。

示例 `.gitignore` 文件

# VuePress 默认临时文件目录
.vuepress/.temp
# VuePress 默认缓存目录
.vuepress/.cache
# VuePress 默认构建生成的静态文件目录
.vuepress/dist

开始使用 VuePress

启动开发服务器

你可以在 package.json 中添加一些 scripts ：

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

运行 docs:dev 脚本可以启动开发服务器:

pnpm docs:dev

VuePress 会在 http://localhost:8080 启动一个热重载的开发服务器。当你修改你的 Markdown 文件时，浏览器中的内容也会自动更新。

构建你的网站

运行 docs:build 脚本可以构建你的网站：

pnpm docs:build

在 docs/.vuepress/dist 目录中可以找到构建生成的静态文件。

反向代理

参考教程：安装及使用

⚠️Nginx Proxy Manager（以下简称NPM）会用到80、443端口，所以本机不能占用（比如原来就有Nginx）

互联网使用请确保完成了域名解析

配置

配置文件

VuePress 站点的基本配置文件是 .vuepress/config.js ，但也同样支持 TypeScript 配置文件。你可以使用 .vuepress/config.ts 来得到更好的类型提示。

具体而言，我们对于配置文件的路径有着约定（按照优先顺序）：

• 当前工作目录 cwd 下：
  • vuepress.config.ts
  • vuepress.config.js
  • vuepress.config.mjs
• 源文件目录 sourceDir 下：
  • .vuepress/config.ts
  • .vuepress/config.js
  • .vuepress/config.mjs

你也可以通过 命令行接口 的 --config 选项来指定配置文件：

vuepress dev docs --config my-config.ts

一个基础的配置文件是这样的：

import { viteBundler } from '@vuepress/bundler-vite'
import { defaultTheme } from '@vuepress/theme-default'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  bundler: viteBundler(),
  theme: defaultTheme(),

  lang: 'zh-CN',
  title: '你好， VuePress ！',
  description: '这是我的第一个 VuePress 站点',
})

客户端配置文件

在大多数情况下，配置文件已经足够帮助你配置好你的 VuePress 站点。不过，有些时候用户们可能希望直接添加一些客户端代码。 VuePress 通过客户端配置文件来支持这种需求：

├─ docs
│  ├─ .vuepress
│  │  ├─ client.js   <--- 客户端配置文件
│  │  └─ config.js   <--- 配置文件
│  └─ README.md
├─ .gitignore
└─ package.json

同样的，我们也有关于客户端配置文件的路径约定（按照优先顺序）：

• 当前工作目录 cwd 下：
  • vuepress.client.ts
  • vuepress.client.js
  • vuepress.client.mjs
• 源文件目录 sourceDir 下：
  • .vuepress/client.ts
  • .vuepress/client.js
  • .vuepress/client.mjs

一个基础的客户端配置文件是这样的：

import { defineClientConfig } from 'vuepress/client'

export default defineClientConfig({
  enhance({ app, router, siteData }) {},
  setup() {},
  rootComponents: [],
})

页面

VuePress 是以 Markdown 为中心的。你项目中的每一个 Markdown 文件都是一个单独的页面。

路由

默认情况下，页面的路由路径是根据你的 Markdown 文件的相对路径决定的。

假设这是你的 Markdown 文件所处的目录结构：

└─ docs
   ├─ guide
   │  ├─ getting-started.md
   │  └─ README.md
   ├─ contributing.md
   └─ README.md

将 docs 目录作为你的 sourceDir ，例如你在运行 vuepress dev docs 命令。此时，你的 Markdown 文件对应的路由路径为：

提示

默认配置下， README.md 和 index.md 都会被转换成 index.html ，并且其对应的路由路径都是由斜杠结尾的。然而，如果你想同时保留这两个文件，就可能会造成冲突。

在这种情况下，你可以设置 pagePatterns 来避免某个文件被 VuePress 处理，例如使用 ['**/*.md', '!**/README.md', '!.vuepress', '!node_modules'] 来排除所有的 README.md 文件。

此外，一些符号如 : 和 + 可能对 vue-router 有特殊含义，因此你应该避免使用它们

Frontmatter

Markdown 文件可以包含一个 YAML Frontmatter 。Frontmatter 必须在 Markdown 文件的顶部，并且被包裹在一对三短划线中间。下面是一个基本的示例：

---
lang: zh-CN
title: 页面的标题
description: 页面的描述
---

你肯定注意到 Frontmatter 中的字段和配置文件中的站点配置十分类似。你可以通过 Frontmatter 来覆盖当前页面的 lang, title, description 等属性。因此，你可以把 Frontmatter 当作页面级作用域的配置。

同样的，VuePress 有一些内置支持的 Frontmatter 字段，而你使用的主题也可能有它自己的特殊 Frontmatter 。

内容

页面的主要内容是使用 Markdown 书写的。VuePress 首先会将 Markdown 转换为 HTML ，然后将 HTML 作为 Vue 单文件组件的 <template> 。

借助 markdown-it 和 Vue 模板语法的能力，基础的 Markdown 可以得到很多的扩展功能。

Markdown

在阅读本章节之前，请确保你已经对 Markdown 有所了解。如果你还不了解 Markdown ，请先学习一些 Markdown 教程。

语法扩展

VuePress 会使用 markdown-it 来解析 Markdown 内容，因此可以借助于 markdown-it 插件来实现 语法扩展 。

本章节将会介绍 VuePress 内置支持的 Markdown 语法扩展。

你也可以通过 markdown 和 extendsMarkdown 来配置这些内置扩展、加载更多 markdown-it 插件、实现你自己的扩展等。

内置

由 markdown-it 内置支持：

• 表格在新窗口打开 (GFM)
• 删除线在新窗口打开 (GFM)

标题锚点

你可能已经注意到，当你把鼠标放在各个章节的标题上时，会显示出一个 # 锚点。点击这个 # 锚点，可以直接跳转到对应章节。

标题锚点扩展由 markdown-it-anchor支持。

链接

在你使用 Markdown 的 链接语法 时， VuePress 会为你进行一些转换。

主题

VuePress 主题为你提供了布局、样式和其他功能，帮助你专注于 Markdown 内容的写作。

默认主题

VuePress 提供了一个默认主题，你当前正在浏览的文档网站就是使用的这个默认主题。

你需要在你的配置文件中通过 theme 配置项来使用它：

import { defaultTheme } from '@vuepress/theme-default'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  theme: defaultTheme({
    // 默认主题配置
    navbar: [
      {
        text: '首页',
        link: '/',
      },
    ],
  }),
})

然而，你可能觉得默认主题不够出色，又或者你不想搭建一个文档网站，而是一个其他类型的网站，比如博客。此时，你可以尝试使用社区主题或者创建本地主题。

社区主题

社区用户创建了很多主题，并将它们发布到了 NPM 上。查看主题本身的文档可以获取更详细的指引。

你可以在 VuePress 市场 中探索更多主题。

插件

官方插件

VuePress 团队提供了一些官方插件。

你需要在你的配置文件中通过 plugins 配置项来使用它们。举例来说，你可以使用 @vuepress/plugin-google-analytic来使用 Google Analytics ：

import { googleAnalyticsPlugin } from '@vuepress/plugin-google-analytics'

export default {
  plugins: [
    googleAnalyticsPlugin({
      id: 'G-XXXXXXXXXX',
    }),
  ],
}

大部分插件只能使用一次，如果同一个插件被多次使用，那么只有最后一次会生效。

然而，部分插件是可以被多次使用的（例如 @vuepress/plugin-container），你应该查看插件本身的文档来获取详细指引。

社区插件

社区用户创建了很多插件，并将它们发布到了 NPM 上。 查看插件本身的文档可以获取更详细的指引。

你可以在 VuePress 市场 中探索更多插件。