vuepress的使用

快速上手

前提条件

VuePress 需要 Node.js (opens new window)>= 8.6

1.安装vuepress

yarn add -D vuepress # npm install -D vuepress

2.创建你的第一篇文档

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

3.在 package.json 中添加 scripts

{

  "scripts": {

    "docs:dev": "vuepress dev docs",

    "docs:build": "vuepress build docs"

  }

}

4.在本地启动服务器

yarn docs:dev # npm run docs:dev

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

目录结构

• 
  
• 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: 客户端应用的增强。
  

默认的页面路由

主题配置

首页

默认的主题提供了一个首页（Homepage）的布局 (用于 这个网站的主页)。想要使用它，需要在你的根级 README.md 中指定 home: true。以下是一个如何使用的例子：

---

home: true

heroImage: /hero.png

heroText: Hero 标题

tagline: Hero 副标题

actionText: 快速上手 →

actionLink: /zh/guide/

features:

- title: 简洁至上

  details: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。

- title: Vue驱动

  details: 享受 Vue + webpack 的开发体验，在 Markdown 中使用 Vue 组件，同时可以使用 Vue 来开发自定义主题。

- title: 高性能

  details: VuePress 为每个页面预渲染生成静态的 HTML，同时在页面被加载的时候，将作为 SPA 运行。

footer: MIT Licensed | Copyright © 2018-present Evan You

---

更多配置项

导航栏

导航栏可能包含你的页面标题、搜索框、 导航栏链接、多语言切换、仓库链接，它们均取决于你的配置。

导航栏 Logo

// .vuepress/config.js

module.exports = {

  themeConfig: {

    logo: '/assets/img/logo.png',

  }

}

导航栏链接

// .vuepress/config.js

module.exports = {

  themeConfig: {

    nav: [

      { text: 'Home', link: '/' },

      { text: 'Guide', link: '/guide/' },

      { text: 'External', link: 'https://google.com' },

      { text: 'test', link: 'test', target:'_self', rel:'' }

    ]

  }

}

设置分组

// .vuepress/config.js

module.exports = {

  themeConfig: {

    nav: [

      {

        text: 'Languages',

        items: [

          { text: 'Chinese', link: '/language/chinese/' },

          { text: 'Japanese', link: '/language/japanese/' }

        ]

      }

    ]

  }

}

侧边栏

想要使 侧边栏（Sidebar）生效，需要配置 themeConfig.sidebar，基本的配置，需要一个包含了多个链接的数组：

// .vuepress/config.js

module.exports = {

  themeConfig: {

    sidebar: [

      '/',

      '/page-a',

      ['/page-b', 'Explicit link text']

    ]

  }

}

省略 .md 拓展名，同时以 / 结尾的路径将会被视为 */README.md，这个链接的文字将会被自动获取到

嵌套的标题链接

默认情况下，侧边栏会自动地显示由当前页面的标题（headers）组成的链接，并按照页面本身的结构进行嵌套，你可以通过 themeConfig.sidebarDepth 来修改它的行为。默认的深度是 1，它将提取到 h2 的标题，设置成 0 将会禁用标题（headers）链接，同时，最大的深度为 2，它将同时提取 h2 和 h3 标题。

显示所有页面的标题链接

// .vuepress/config.js

module.exports = {

  themeConfig: {

    displayAllHeaders: true // 默认值：false

  }

}

活动的标题链接

默认情况下，当用户通过滚动查看页面的不同部分时，嵌套的标题链接和 URL 中的 Hash 值会实时更新，这个行为可以通过以下的配置来禁用：

// .vuepress/config.js

module.exports = {

  themeConfig: {

    activeHeaderLinks: false, // 默认值：true

  }

}

侧边栏分组

// .vuepress/config.js

module.exports = {

  themeConfig: {

    sidebar: [

      {

        title: 'Group 1',   // 必要的

        path: '/foo/',      // 可选的, 标题的跳转链接，应为绝对路径且必须存在

        collapsable: false, // 可选的, 默认值是 true,

        sidebarDepth: 1,    // 可选的, 默认值是 1

        children: [

          '/'

        ]

      },

      {

        title: 'Group 2',

        children: [ /* ... */ ],

        initialOpenGroupIndex: -1 // 可选的, 默认值是 0

      }

    ]

  }

}

侧边栏的每个子组默认是可折叠的，你可以设置 collapsable: false 来让一个组永远都是展开状态。

多个侧边栏

.

├─ README.md

├─ contact.md

├─ about.md

├─ foo/

│  ├─ README.md

│  ├─ one.md

│  └─ two.md

└─ bar/

   ├─ README.md

   ├─ three.md

   └─ four.md

注意

确保 fallback 侧边栏被最后定义。VuePress 会按顺序遍历侧边栏配置来寻找匹配的配置

搜索框

内置搜索

你可以通过设置 themeConfig.search: false 来禁用默认的搜索框，或是通过 themeConfig.searchMaxSuggestions 来调整默认搜索框显示的搜索结果数量

// .vuepress/config.js

module.exports = {

  themeConfig: {

    search: false,

    searchMaxSuggestions: 10

  }

}

最后更新时间

你可以通过 themeConfig.lastUpdated 选项来获取每个文件最后一次 git 提交的 UNIX 时间戳(ms)，同时它将以合适的日期格式显示在每一页的底部：

// .vuepress/config.js

module.exports = {

  themeConfig: {

    lastUpdated: 'Last Updated', // string | boolean

  }

}

上 / 下一篇链接

上一篇和下一篇文章的链接将会自动地根据当前页面的侧边栏的顺序来获取。

你可以通过 themeConfig.nextLinks 和 themeConfig.prevLinks 来全局禁用它们：

// .vuepress/config.js

module.exports = {

  themeConfig: {

    // 默认值是 true 。设置为 false 来禁用所有页面的 下一篇 链接

    nextLinks: false,

    // 默认值是 true 。设置为 false 来禁用所有页面的 上一篇 链接

    prevLinks: false

  }

}

Git 仓库和编辑链接

当你提供了 themeConfig.repo 选项，将会自动在每个页面的导航栏生成生成一个 GitHub 链接，以及在页面的底部生成一个 "Edit this page" 链接。

// .vuepress/config.js

module.exports = {

  themeConfig: {

    // 假定是 GitHub. 同时也可以是一个完整的 GitLab URL

    repo: 'vuejs/vuepress',

    // 自定义仓库链接文字。默认从 `themeConfig.repo` 中自动推断为

    // "GitHub"/"GitLab"/"Bitbucket" 其中之一，或是 "Source"。

    repoLabel: '查看源码',

    // 以下为可选的编辑链接选项

    // 假如你的文档仓库和项目本身不在一个仓库：

    docsRepo: 'vuejs/vuepress',

    // 假如文档不是放在仓库的根目录下：

    docsDir: 'docs',

    // 假如文档放在一个特定的分支下：

    docsBranch: 'master',

    // 默认是 false, 设置为 true 来启用

    editLinks: true,

    // 默认为 "Edit this page"

    editLinkText: '帮助我们改善此页面！'

  }

}

静态资源

静态资源都存放在public文件下

图片的使用

<img :src="$withBase('/frontend/prototype-chains.jpg')" alt="prototype-chains">

logo

// .vuepress/config.js

module.exports = {

  themeConfig: {

    logo: '/logo.png',

  }

}

首页logo

// README.md

---

heroImage: /app.png

---

Markdown扩展

Emoji

你可以在这个列表 找到所有可用的 Emoji。

自定义容器

::: warning

这是一个警告

:::

::: danger

这是一个危险警告

:::

::: details

这是一个详情块，在 IE / Edge 中不生效

:::

你也可以自定义块中的标题：

::: danger STOP

危险区域，禁止通行

:::

::: details 点击查看代码

这是代码

:::

代码块中的语法高亮

VuePress 使用了 Prism 来为 markdown 中的代码块实现语法高亮。Prism 支持大量的编程语言，你需要做的只是在代码块的开始倒勾中附加一个有效的语言别名：

    ```

    export default {

      name: 'MyComponent',

      // ...

    }

    ```

在 Prism 的网站上查看 合法的语言列表。

代码块中的行高亮

    ``` js {4}

    export default {

      data () {

        return {

          msg: 'Highlighted!'

        }

      }

    }

    ```

除了单行以外，你也可指定多行，行数区间，或是两者都指定。

• 
  
• 行数区间: 例如 {5-8}, {3-10}, {10-17}
  
• 多个单行: 例如 {4,7,9}
  
• 行数区间与多个单行: 例如 {4,7-13,16,23-27,40}
  

行号

// config.js

module.exports = {

  markdown: {

    lineNumbers: true

  }

}

导入代码段

<<< @/docs/.vuepress/code/test.js

使用vue组件

所有在 .vuepress/components 中找到的 *.vue 文件将会自动地被注册为全局的异步组件，如：

.

└─ .vuepress

   └─ components

      ├─ demo-1.vue

      ├─ OtherComponent.vue

      └─ Foo

         └─ Bar.vue

你可以直接使用这些组件在任意的 Markdown 文件中（组件名是通过文件名取到的）：

<demo-1/>

<OtherComponent/>

<Foo-Bar/>

插件

@vuepress/plugin-back-to-top

安装

yarn add -D @vuepress/plugin-back-to-top

# OR npm install -D @vuepress/plugin-back-to-top

使用

module.exports = {

  plugins: ['@vuepress/back-to-top']

}

构建与部署

Github Pages 是面向用户、组织和项目开放的公共静态页面搭建托管服务，站点可以被免费托管在 Github 上，你可以选择使用 Github Pages 默 认提供的域名 github.io 或者自定义域名来发布站点。不仅免除了租服务器的麻烦，而且部署起来非常轻松。简而言之，在GitHub Pages上发布博客是非常好的选择。

创建两个仓库

1、amjanney.github.io，站点仓库，用来存放打包后的文件。

2、docs，用来放vuepress写的文档。

github.io会默认读取根目录下的index.html作为首页。所以我们要做的就是把打包后的vuepress文档上传到创建的名为<username>.github.io的仓库下。

仓库地址

github.com/amjanney/am…

github.com/amjanney/do…

发布

在docs下面有个deploy.sh文件，代码如下：

#!/usr/bin/env sh


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

set -e


# 生成静态文件

npm run docs:build


# 进入生成的文件夹

cd docs/.vuepress/dist


# 如果是发布到自定义域名

# echo 'www.example.com' > CNAME


git init

git add -A

git commit -m 'deploy'


# 如果发布到 https://amjanney.github.io

git push -f https://github.com/amjanney/amjanney.github.io.git master

在package.json文件中配置命令

"deploy": "bash deploy.sh"

运行

npm run deploy

会执行deploy.sh中的命令，先打包vuepress文件，在docs/.vuepress/dist下面打包后的文件，cd到这个文件下面，通过git在上传到amjanney.github.io.git仓库，这时候访问amjanney.github.io/，文档就已经生效了。

每次更改了文件，就需要执行npm run deploy命令，更新文档。

当然这个过程可以集成一下，每次push代码到master的时候，自动出发npm run deploy过程。

更多部署方式移步链接。