VuePress 使用笔记

最近帮组内的一个产品搭建官网，需要一个酷炫点的首页，然后就是产品使用手册，查了几个类型的静态网站生成器，最后因为首页还是有一些定制化的需求，加上对 Vue 比较熟悉，所以选择了功能强大的 VuePress。

1. 搭建项目

这一步没什么需要注意的，跟着官网的教程一步步执行就可以。VuePress 需要 Node.js >= 8.6，我的 Node.js 环境是 v12。

# 创建并进入一个新目录
mkdir vuepress-starter && cd vuepress-starter
# 使用你喜欢的包管理器进行初始化
yarn init # npm init
# 将 VuePress 安装为本地依赖
yarn add -D vuepress # npm install -D vuepress
# 创建你的第一篇文档
mkdir docs && echo '# Hello VuePress' > docs/README.md
复制代码

然后在 package.json 中添加一些 scripts

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
复制代码

在本地启动服务器

yarn docs:dev # npm run docs:dev
复制代码

2. 项目结构

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

.
├── docs
│   ├── .vuepress (可选的)      # 用于存放全局的配置、组件、静态资源等。
│   │   ├── components (可选的) # 该目录中的 Vue 组件将会被自动注册为全局组件。
│   │   ├── theme (可选的)      # 用于存放本地主题。
│   │   ├── public (可选的)     # 静态资源目录。
│   │   ├── styles (可选的)     # 用于存放样式相关的文件。
│   │   ├── templates (可选的, 谨慎配置)    # 存储 HTML 模板文件。
│   │   ├── config.js (可选的)  # 配置文件的入口文件
│   │   └── enhanceApp.js (可选的)  # 客户端应用的增强。
│   ├── README.md
│   ├── guide
│   │   └── README.md
│   └── config.md
│ 
└── package.json
复制代码

所有的文档相关的文件都写在 docs 文件夹下，所有的页面都对应一个 markdown 文件。

对于上述的目录结构，默认页面路由地址如下：

文件的相对路径	页面路由地址
/README.md	/
/guide/README.md	/guide/
/config.md	/config.html

3. 页面配置

导航栏 Logo 和网页 favicon 配置

在 docs/.vuepress/public 下添加 logo.png 和 idec.ico 图片文件，然后在 .vuepress/config.js 配置

// docs/.vuepress/config.js
module.exports = {
    head: [
        ['link', { rel: 'icon', href: '/idec.ico' }]
    ],
    themeConfig: {
        logo: '/logo.jpg',
    },
};
复制代码

显示效果：

导航栏链接

可以通过 themeConfig.nav 增加一些导航栏链接

themeConfig: {
    nav: [
        { text: 'Home', link: '/' },
        { text: 'Part1', link: '/part1/' },
        { text: 'Part2', link: '/part2/' },
        { text: 'External', link: 'http://google.com' },
    ]
}
复制代码

侧边栏配置

1. 你可以省略 .md 拓展名，同时以 / 结尾的路径将会被视为 */README.md，这个链接的文字将会被自动获取到（无论你是声明为页面的第一个 header，还是明确地在 YAML front matter 中指定页面的标题）。如果你想要显示地指定链接的文字，使用一个格式为 [link, text] 的数组。

themeConfig: {
    sidebar: [
        '/',
        '/part1/',
        ['/part1/chapter1', '随便起个标题，会显示在左边栏']
    ]
},
复制代码

对应文件结构

|-docs
    └──.vuepress
    └──part1
        └──chapter1.md	# 对应 /part1/chapter1
        └──README.md		# 对应 /part1/
    └──README.md		# 对应 /
复制代码

2. 左边栏分组显示

themeConfig: {
    sidebar: [
        {
            title: 'part1',   // 必要的
            path: '/part1/',      // 可选的, 标题的跳转链接，应为绝对路径且必须存在
            collapsable: false, // 可选的, 默认值是 true,
            sidebarDepth: 1,    // 可选的, 默认值是 1
            children: [
                ['/part1/chapter1', '随便起个标题，会显示在左边栏'],
                '/part1/chapter2'
            ]
        },
        {
            title: 'part2',   // 必要的
            children: [
                '/part2/',
                '/part2/chapter1',
                '/part2/chapter2',
            ]
        },
    ]
}
复制代码

文件结构及显示效果

3. 多个左边栏

文件结构不变，把 sidebar 改成如下形式，左边栏将分别在 '/part1/' 和 '/part2/' 路径下显示不同的内容。

themeConfig: {
    sidebar: {
        '/part1/': [
            '',     	/* /part1/ */
            'chapter1',  /* /part1/chapter1.html */
            'chapter2'   /* /part1/chapter2.html */
        ],
        '/part2/': [
            '',     	/* /part2/ */
            'chapter1',  /* /part2/chapter1.html */
            'chapter2'   /* /part2/chapter2.html */
        ],
    }
}
复制代码

效果如图：

首页配置

默认的主题提供了一个首页（Homepage）的布局。想要使用它，需要在你的根级 README.md 的 YAML front matter 指定 home: true。

可以使用默认的首页布局，配置首页标题，图片等内容。

---
home: true
heroImage: /logo.png
heroText: Hero 标题
tagline: Hero 副标题
actionText: 快速上手 →
actionLink: /part1/
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
---
复制代码

4. 自定义页面

自定义样式

如果要对默认预设的样式进行简单的替换，或者定义一些变量供以后使用，你可以创建一个 .vuepress/styles/palette.styl 文件。具体参考 palette-styl。

VuePress 提供了一种添加额外样式的简便方法。你可以创建一个 .vuepress/styles/index.styl 文件。这是一个 Stylus 文件，但你也可以使用正常的 CSS 语法。

自定义页面类

在页面的 YAML front matter 中声明一个 pageClass

---
pageClass: custom-page-class
---
复制代码

然后在 .vuepress/styles/index.styl 设置对应样式

/* .vuepress/styles/index.styl */
.theme-container.custom-page-class {
  color: tomato;
}
复制代码

特定页面的自定义布局

可以在页面 YAML front matter 指定组件。

---
layout: Home
---
复制代码

然后实现 Home 组件 .vuepress/components/Home.vue，这样页面将完全自定义，没有导航栏和左边栏等默认内容。比较适合自定义的首页。

<template>
    <div class="home-container">
        自定义布局-Home
    </div>
</template>

<script>
    export default {
        name: 'Home'
    }
</script>

<style scoped>
    .home-container {
        text-align: center;
        color: tomato;
    }
</style>
复制代码

引入第三方库

由于需要一个酷炫点的首页，我还是想引入 Element 组件库（这和酷炫有什么关系啊喂）

通过 yarn add element-ui 安装，然后需要在 .vuepress/enhanceApp.js 进行配置。

// .vuepress/enhanceApp.js
// 全局注册 Element 组件库
import ElementUI from 'element-ui';
import 'element-ui/lib/theme-chalk/index.css';

export default ({
                    Vue, // VuePress 正在使用的 Vue 构造函数
                    options, // 附加到根实例的一些选项
                    router, // 当前应用的路由实例
                    siteData // 站点元数据
                }) => {
    Vue.use(ElementUI)
}
复制代码

然后发现报错了=。=

assign.js?3f6b:1 Uncaught Error: Cannot find module 'core-js/library/fn/object/assign'

具体可以看这个 github.com/vuejs/vuepr… 反正就是 依赖的 core-js 版本不一致导致的冲突，运行 yarn add [email protected] 可以解决问题。

现在可以在 markdown 文件中直接使用 element 组件了。

参考

• vuepress.vuejs.org/zh/guide/
• vuepress.vuejs.org/zh/theme/de…
• segmentfault.com/a/119000002…