How to use Vuepress

Project structure

├─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 distinction
Vuerpess 0.x version and 1.x versions rely on different command download

Based on node.js> = 8+ installed and set up projects based on version 1.x

If your existing project relied webpack 3.x, it recommended Yarn instead of npm install VuePress. Because in this case, npm will generate an error dependency tree.
:::

Global Installation

If you just want to try VuePress, you can install it globally:

# 安装
yarn global add vuepress@next # 或者：npm install -g vuepress@next

# 新建一个 markdown 文件
echo '# Hello VuePress!' > README.md

# 开始写作
vuepress dev .

# 构建静态文件
vuepress build .

Existing projects

If you want to use VuePress in an existing project, and you want to manage documents in the project, it should VuePress installed as a local dependency. Installed as local rely allows you to use continuous integration tools or other services (such as Netlify) to help deploy automatically every time you submit the code.

# 将 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

Placed package.json

Executes commands at the root path in the project:

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

Then, in package.jsonRiga some scripts, as follows:

{
  "name": "vuepress",
  "version": "1.0.0",
  "description": "vuepress",
  "main": "index.js",
  "repository": "https://github.com/P-Sansei/vuepress.git",
  "author": "penghe.yu <[email protected]>",
  "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"
  }
}

After adding Well, then execute the following command to add project dependencies

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

Start the test

# 启动命令
yarn dev

# 生成静态的 HTML 文件，运行
yarn build

Deployed to GitHub Pages

Created under the project root path deploy.sh bat file , the file configuration is as follows:

#!/usr/bin/env sh

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
yarn build

# 进入生成的文件夹
cd docs/.vuepress/dist

# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果发布到 https://<USERNAME>.github.io/<REPO>
git push -f https://github.com/P-Sansei/vuepress.git master:gh-pages

cd -

Then execute the following commands in the Project root path:

# 部署
yarn deploy

By default, the file will be generated .vuepress/dist, you can also pass .vuepress/config.jsthe destmodified field, the resulting file can be deployed to any static files on the server

More reference to the official website