使用Vuepress 搭建文档网站并进行配置

科技爱好者

5 年前

Vuepress是一VUE驱动的静态网站生成器，被广泛用于文档网站的搭建，同时也可以用来搭建博客。由于是静态网站，所以访问速度很快，并且使用markdown进行书写，对程序员比较友好。本文介绍下如何使用Vuepress 搭建文档网站，并进行配置，可以说本文是使用Vuepress 的快速指南。

一、Vuepress 介绍

VuePress 由两部分组成：第一部分是一个极简静态网站生成器，它包含由 Vue 驱动的主题系统和插件 API，另一个部分是为书写技术文档而优化的默认主题，它的诞生初衷是为了支持 Vue 及其子项目的文档需求。

和Vuepress 类似的有Hexo、docsify、Gitbook等，但我认为Vuepress 是最好的文档书写网站，以下是为什么选择Vuepress 而不选择其他的理由：

Nuxt

VuePress 能做的事情，Nuxt 理论上确实能够胜任，但 Nuxt 是为构建应用程序而生的，而 VuePress 则专注在以内容为中心的静态网站上，同时提供了一些为技术文档定制的开箱即用的特性。

Docsify / Docute

这两个项目同样都是基于 Vue，然而它们都是完全的运行时驱动，因此对 SEO 不够友好。如果你并不关注 SEO，同时也不想安装大量依赖，它们仍然是非常好的选择！

Hexo

Hexo 最大的问题在于他的主题系统太过于静态以及过度地依赖纯字符串，同时，Hexo 的 Markdown 渲染的配置也不是最灵活的。

GitBook

GitBook 最大的问题在于当文件很多时，每次编辑后的重新加载时间长得令人无法忍受。它的默认主题导航结构也比较有限制性，并且，主题系统也不是 Vue 驱动的。GitBook 背后的团队如今也更专注于将其打造为一个商业产品而不是开源工具。

二、安装Vuepress

安装Vuepress 有两种方式，因为之前没有项目，所以选择了全局安装，安装过程比较简单。

1.安装Node.js

要求Node.js版本大于8.0,之前写过在树莓派上安装的文章，其他Linux系统安装同样也可以参考，文章链接：在树莓派上安装最新版Nodejs 。

2.安装vuepress

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

# 创建项目目录
mkdir raspberry && cd raspberry

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

# 预览网站
vuepress dev .

这里的raspberry为项目名称，可以自定义。

完成后屏幕上就会出现预览网站的地址，像下面这样：

好，这里Vuepress就成功的搭建起来了，但是现在网站里什么内容也没有，网站首页也只是一个简单的Hello VuePress!，所以我们还要进行下一步的配置，让网站变得好看。

三、配置 Vuepress

配置文件

如果没有任何配置，这个网站将会是非常局限的，用户也无法在你的网站上自由导航。为了更好地自定义你的网站，让我们首先在你的文档目录下创建一个 .vuepress 目录，所有 VuePress 相关的文件都将会被放在这里。你的项目结构可能是这样：

.
├─ raspberry
│  ├─ README.md
│  ├─ docs
│  └─ .vuepress
│     └─ config.js
│     └─ dist
│     └─ public

一个 VuePress 网站必要的配置文件是 .vuepress/config.js，网站的title、页面布局，页面目录以及插件的配置，都在这个文件中，这个文件包含网站所有的配置信息。

目录内容为：

raspberry/.vuepress: 用于存放全局的配置、组件、静态资源等。
raspberry/.vuepress/public: 静态资源目录。
raspberry/.vuepress/config.js: 配置文件的入口文件，也可以是 YML 或 toml。

所以网站的图片全部放在.vuepress/public目录下。

主题配置

主题使用的是默认主题，在根目录的README.md中写入以下配置：

---
home: true
heroImage: /logo.png
heroText: 树莓派中文文档
tagline: 玩转树莓派如此简单
actionText: 快速上手 →
actionLink: /start/
features:
- title: 快速上手
  details: 树莓派是什么，树莓派怎么购买，怎么快速启动，都有那些树莓派版本？在这里都可以找到答案。
- title: 基础知识
  details: 树莓派硬件介绍和常用命令，掌握树莓派的基础知识，可以做一些树莓派的入门实验。
- title: 高手进阶
  details: 树莓派更多的功能，连接物联网，接入传感器网络，或者使用树莓派搭建网站，使用树莓派完成更高级的应用。
footer: MIT Licensed | Copyright © 2020-科技爱好者博客（http://www.Lxx1.com）
---

这里要注意的是，首页的logo图片要放在.vuepress/public文件夹下，另外，网站的favicon.ico 也同样放在public文件夹下，heroText为标题，tagline为副标题，features下是三段话，可以按照自己的实际进行修改。

保存后，使用vuepress dev .(在树莓派目录下，若不在这个目录，应该使用vuepress dev /raspberry命令)查看效果。

功能配置

导航栏链接

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

// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      { text: 'External', link: 'https://google.com' },
    ]
  }
}

开启不同的侧边栏

如果你想为不同的页面组来显示不同的侧边栏，首先，将你的页面文件组织成下述的目录结构：

.
├─ README.md
├─ contact.md
├─ about.md
├─ foo/
│  ├─ README.md
│  ├─ one.md
│  └─ two.md
└─ bar/
   ├─ README.md
   ├─ three.md
   └─ four.md

接着，遵循以下的侧边栏配置：

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: {
      '/foo/': [
        '',     /* /foo/ */
        'one',  /* /foo/one.html */
        'two'   /* /foo/two.html */
      ],

      '/bar/': [
        '',      /* /bar/ */
        'three', /* /bar/three.html */
        'four'   /* /bar/four.html */
      ],

      // fallback
      '/': [
        '',        /* / */
        'contact', /* /contact.html */
        'about'    /* /about.html */
      ]
    }
  }
}

最后更新时间

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

module.exports = {
  themeConfig: {
    lastUpdated: 'Last Updated', // string | boolean
  }
}

这里要注意⚠️的是，只有将文件提交到git后才会显示最后更新时间。显示效果如下：

看下树莓派文档使用的配置文件：

// .vuepress/config.js
module.exports = {
  base: "/pi/", //网站路径
  title: '树莓派中文文档', //导航栏左侧文字
  description: '树莓派中文文档，Rasperry pi文档, 树莓派资料，树莓派新手教程，树莓派使用', //网站描述，用于SEO
  head: [
    ['link', { rel: 'icon', href: '/favicon.ico' }]
  ],
  themeConfig: {
    nav: [   //导航栏链接
      { text: '首页', link: '/' },
      { text: '快速上手', link: '/start/' },
      { text: '基础知识', link: '/basis/' },
      { text: '高手进阶', link: '/advanced/' },
      { text: '科技爱好者博客', link: 'http://www.tujing.site' },
    ],

     sidebar: {    //侧边栏配置
      '/start/': [
        '',
        'start',  /* /foo/one.html */
        'raspberry_pi_version'   /* /foo/two.html */
      ],
    '/basis/': [
      '',
      'commmand',
      'power',
      'raspi',
      'sudo',
      'network',
      ],
    '/advanced/': [
      '',
      'service',
      'info_python',
      ],
    },
    sidebarDepth: 2 ,   
    lastUpdated: 'Last Updated',   //显示最后更新时间
    smoothScroll: true,
    displayAllHeaders: true, // 默认值：false
    
  }
}

完成后的整体效果是这样的：