本文教程使用vuepress v2.0.0-beta.26(vuepress/vuepress-next)

2.x与1.x的用法基本相近, 但是插件和主题无法共用(如Vue2.x 与 Vue3.x)

为什么要升级2.x

1. 想要使用Vue3语法和TypeScript的话
2. 单纯想尝鲜，拥抱变化
3. 想使用webpack或者vite来作为打包工具

基本使用

1. 创建并初始化项目

mkdir vuepress-demo
cd vuepress-demo
git init
yarn init

2. 安装Vuepress

  yarn add -D vuepress@next

3. 创建一篇markdown文档

这里我们在docs文件夹下进行创建（可以自行命名文件夹）, 可以手动进行创建， 也可以使用下面命令快速创建

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

4. 在package.json的scripts中添加启动以及打包命令配置

这里 docs 对应第3步你所创建的文件夹名称

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

5. 启动本地服务进行测试

yarn docs:dev

VuePress会在 http://localhost:8080 启动一个开发服务器， 支持热重载。

目录结构

.
├── docs
│   ├── .vuepress (可选的, 用于存放全局的配置、组件、静态资源等。)
│   │   ├── components (可选的, 该目录中的 Vue 组件将会被自动注册为全局组件)
│   │   ├── theme (可选的, 用于存放本地主题)
│   │   │   └── Layout.vue
│   │   ├── public (可选的, 静态资源目录)
│   │   ├── styles (可选的, 用于存放样式相关的文件)
│   │   │   ├── index.styl (将会被自动应用的全局样式文件，会生成在最终的 CSS 文件结尾，具有比默认样式更高的优先级。)
│   │   │   └── palette.styl (用于重写默认颜色常量，或者设置新的 stylus 颜色常量。)
│   │   ├── templates (可选的, 谨慎配置, 存储 HTML 模板文件)
│   │   │   ├── dev.html (用于开发环境的 HTML 模板文件)
│   │   │   └── ssr.html (构建时基于 Vue SSR 的 HTML 模板文件)
│   │   ├── config.ts (可选的, 配置文件的入口文件，也可以是 YML 或 toml)
│   │   └── enhanceApp.js (可选的, 客户端应用的增强)
│   │ 
│   ├── README.md
│   ├── guide
│   │   └── README.md
│   └── config.md
│ 
└── package.json

主题的使用及开发

主题推荐

• vuepress-theme-hope

在config.ts中配置theme属性来使用自定义主题

自定义主题放置在📂.vuepress/theme文件夹下

export default {
  theme: path.resolve(__dirname, './theme/index.ts')
}

开发自定义主题

1. 在📂.vuepress/theme文件夹下新建index.ts作为主题配置文件

import { path } from '@vuepress/utils'
export default {
  name: 'vuepress-theme-demo', // 主题前缀为vuepress-theme-
  extends: '@vuepress/theme-default', // 继承默认主题(可选)
  layouts: path.resolve(__dirname, './layouts'), // 指定主题布局组件文件夹
}

2. 在📂.vuepress/theme下新建layouts文件夹来存放主题布局组件

自定义主题的layouts下必须含有 Layout.vue 和 404.vue

插件的使用及开发

插件用法

在.vuepress/config.ts文件中配置plugins字段来使用插件, 配置方法有以下几种

1. 本地插件可以使用使用plugins: [require(./my-plugin.js)]方式
2. 发布到npm的插件使用plugins: ['xxx']方式
3. 如果发布到npm的插件以vuepress-plugin-开头, 则可以省略前缀直接使用, 比如vuepress-plugin-xxx可以直接用plugins: ['xxx']的方式使用

active-header-links

页面滚动的时候自动高亮TOC对应链接

组件开发

常见需求以及方案

1. 覆盖默认主题样式

2. 使用自定义frontmatter变量

添加: 在markdown文件上方的frontmatter区域添加自定义的变量, 如demo: true

使用: 在markdown文件中使用{{ $frontmatter.demo }}的方式来使用