VuePress快速上手(默认主题)

简要介绍

VuePress是一个能够将我们编写的markdown文件转换为html文件的一个技术，通过一定规则的限制，并配合 githubpages 可以方便的将我们的多个或一个markdown文件转换为网页并部署在服务器上，供其自由跳转，并添加一些额外的链接。

同github相连接，在浏览网页的同时，我们可以设置允许其对github上的文件进行修改申请。

详细介绍移步：vuePress中文网 - 介绍

安装vuePress

仅介绍默认主题，现有项目中使用 VuePress 管理文档，从步骤 3 开始。

步骤一：

创建并进入一个新目录

mkdir vuepress-starter && cd vuepress-starter

步骤二：

使用你喜欢的包管理器进行初始化

yarn init # npm init

步骤三：现有项目中使用 VuePress 管理文档，从此处开始

将 VuePress 安装为本地依赖（现有项目中使用 VuePress 管理文档从这里开始）

我们已经不再推荐全局安装 VuePress

yarn add -D vuepress # npm install -D vuepress

TIPS

若项目中依赖了webpack3.x，推荐使用yarn而不是npm来安装VuePress，npm会产生错的依赖树。

步骤四：

创建文档

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

步骤五：

在 package.json 中添加一些 scripts代码

这一步骤是可选的，推荐完成。下文中默认这些 scripts 已经被添加。

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

在现有项目中要确保vue版本与vuepress版本一致。

可在package.json中更改版本号，通过 cnpm install 或者 npm install 来更换版本，推荐cnpm。也可自行百度。

步骤六：

在本地启动服务器

yarn docs:dev # npm run docs:dev

---

至此，项目可以在本地运行。

完善目录结构(满足基本需求)

.
├── docs
│   ├── .vuepress
│   │   ├── public
│   │   ├── styles
│   │   │   └── palette.styl
│   │   └── config.js
│   │
│   ├── README.md
│   ├── guide
│   │   └── README.md
│   └── config.md
│ 
└── package.json

VuePress 遵循 “约定优于配置” 的原则，推荐的目录结构如下：

// 完整目录结构
.
├── docs
│   ├── .vuepress (可选的)
│   │   ├── components (可选的)
│   │   ├── theme (可选的)
│   │   │   └── Layout.vue
│   │   ├── public (可选的)
│   │   ├── styles (可选的)
│   │   │   ├── index.styl
│   │   │   └── palette.styl
│   │   ├── templates (可选的, 谨慎配置)
│   │   │   ├── dev.html
│   │   │   └── ssr.html
│   │   ├── config.js (可选的)
│   │   └── enhanceApp.js (可选的)
│   │ 
│   ├── README.md
│   ├── guide
│   │   └── README.md
│   └── config.md
│ 
└── package.json

注意

请留意目录名的大写。

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

开启首页展示

在docs目录(根目录)下的README.md文件写下

---
home: true
heroImage: /img/hero.png # 此处需注意文件路径，public下的文件会被复制到生成目录的根目录。img需自行判断是否添加
heroText: Hero 标题
tagline: Hero 副标题
actionText: 快速上手 →
actionLink: /guide/	 # 此处的guide指的是跳转到对应文件夹，默认加载其内的README.md文件࿰