如何使用 Vuepress

项目结构

├─docs│  ├─.vuepress                --vuepress相关文件路径 (主要配置)│  │  ├─dist                  --build 打包生成路径 (自定义)│  │  ├─nav                   --导航条配置 (自定义)│  │  │  └─ zh.js             --自定义导航条配置│  │  ├─plugins               --插件配置 (自定义)│  │  │  └─ pluginsConf.js    --自定义插件配置│  │  ├─sidebar               --侧边栏配置 (自定义)│  │  │  └─ menu.js           --自定义侧边栏配置│  │  ├─public                --静态资源存放│  │  └─config.js             --网站必要的配置文件 (主要配置)│  ├─changelog                --自定义日志模块│  │    └─......│  ├─docker                   --自定义Docker模块│  │    └─......│  └─guide                    --自定义指南模块│       └─......        ├─README.md                   -- 自定义首页信息 (主要配置)├─.gitignore                  -- 忽略上传文件├─deploy.sh                   -- 自定义打包部署命令行脚本 (主要配置)├─package.json                -- 脚本配置文件 (主要配置)

::: warning 注意区分
Vuerpess 0.x版本和 1.x 版本 依赖下载命令不同

基于 node.js >= 8 安装 且项目基于 1.x 版 搭建

如果你的现有项目依赖了 webpack 3.x，推荐使用 Yarn 而不是 npm 来安装 VuePress。因为在这种情形下，npm 会生成错误的依赖树。
:::

全局安装

如果你只是想尝试一下 VuePress，你可以全局安装它：

# 安装yarn global add vuepress@next # 或者：npm install -g vuepress@next# 新建一个 markdown 文件echo '# Hello VuePress!' > README.md# 开始写作vuepress dev .# 构建静态文件vuepress build .

现有项目

如果你想在一个现有项目中使用 VuePress，同时想要在该项目中管理文档，则应该将 VuePress 安装为本地依赖。作为本地依赖安装让你可以使用持续集成工具，或者一些其他服务（比如 Netlify）来帮助你在每次提交代码时自动部署。

# 将 VuePress 作为一个本地依赖安装yarn add -D vuepress@next # 或者：npm install -D vuepress@next# 新建一个 docs 文件夹mkdir docs# 新建一个 markdown 文件echo '# Hello VuePress!' > docs/README.md# 开始写作npx vuepress dev docs

配置 package.json

在项目根路径下里执行命令:

# 生成配置 package.json 文件yarn init

接着，在 package.json 里加一些脚本，如下：

{  "name": "vuepress",  "version": "1.0.0",  "description": "vuepress",  "main": "index.js",  "repository": "https://github.com/P-Sansei/vuepress.git",  "author": "penghe.yu <[e-mail]>",  "license": "MIT",  "scripts": {    "dev": "vuepress dev docs",    "build": "vuepress build docs",    "deploy": "deploy.sh"  },  "devDependencies": {    "@vuepress/plugin-back-to-top": "^1.0.0-alpha.47",    "vuepress": "^1.0.0-alpha.48"  }}

添加好之后，接着执行如下命令添加项目依赖

# 根据 package.json 的配置 生成 node_modulesyarn install

启动测试

# 启动命令yarn dev# 生成静态的 HTML 文件，运行yarn build

部署到 GitHub Pages

在项目根路径下创建 deploy.sh bat文件, 文件配置如下:

#!/usr/bin/env sh# 确保脚本抛出遇到的错误set -e# 生成静态文件yarn build# 进入生成的文件夹cd docs/.vuepress/dist# 如果是发布到自定义域名# echo 'www.example.com' > CNAMEgit initgit add -Agit commit -m 'deploy'# 如果发布到 https://<USERNAME>.github.io/<REPO>git push -f https://github.com/P-Sansei/vuepress.git master:gh-pagescd -

接着在项目根路径下执行如下命令：

# 部署yarn deploy

默认情况下，文件将会被生成在 .vuepress/dist，你也可以通过 .vuepress/config.js 中的 dest 字段来修改，生成的文件可以部署到任意的静态文件服务器上