Vuepress & Reco主题备忘

0. 前言

• VuePress文档：英文版，中文版
  • 英文版的文档比中文版的新，但大多数内容中文版都有。
• Reco主题官网
  • 注意，Reco 主题知识 VuePress 官方默认主题的扩展，不是一个全新的主题。
• 概述
  • 正如我在以前的博客里提到的，其实我对VuePress的印象很不好，主要原因在于，感觉VuePress的文档对于新手（前端小白）来说非常不友好。
  • 公平地说，在我硬着头皮研究了一段时间，对整体比较熟悉之后，感觉文档还是可以的。（看来，不同受众不同感受）。
  • 我其实比较烂，以前一直使用Hexo Next，现在研究VuePress的主要原因是：
    • 自己的团队要输出一些文档，目前使用的是Gitbook。
    • 团队文档的主要需求是：能够快速实现评论功能，必须部署在内网（内网有搭建Gitlab）。
    • 寻找之后，发现Vusse插件能够通过Gitlab Issue来实现评论功能，而Vussue不支持Hexo、Doscify，单对于VuePress支持非常好。

1. 感兴趣的功能

1.1. 页面介绍

• 封面
  • 来源：默认主题功能。
  • 其他：reco提供了一个博客主题的封面，没仔细研究过。
• 具体使用参考 文档
  • 文档形式封面的参考配置以及效果如下

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

• 导航栏
  • 来源：默认主题功能。
  • 定义方式还是直接参考文档吧。
  • 提供的功能：
    • 普通超链接
    • 下拉菜单（可分组）
  • 举例：下图中 Guide/Config Reference/Plugin/Theme都是普通超链接，Learn More是分组的下拉菜单，Language是无分组的下拉菜单。

• 左侧边栏
  • 来源：默认主题自带。
  • 作用：用来表示多级目录，可能是文章标题，也可能是文章内的章节标题。
  • 提供的功能：
    • 多级、分组管理，可设置最大深度，可设置组内文章是否展开。
    • 分类名可作为超链接。
    • 可以有多个侧边栏（即不同页面显示的侧边栏不同）。
  • 具体使用请参考文档。
  • 举例：下图中，Theme 是分类名称，Introduction/Using a theme等是文档名称，Homepage/Navbar以及再下一级是文章内章节名称。

• 右侧边栏
  • 来源：Reco附加功能。
  • 作用：在使用Reco时，左侧边栏只显示文章多级管理，而不显示文章内章节标题；右侧侧边栏专门用于展示文章内章节标题。
  • 需要先进行配置，具体使用请参考文档。
  • 举例：

1.2. Markdown 编辑功能

• 基本语法（自带）：标题、超链接、列表、引用、代码块。
• 数学公式（插件）
  • 安装插件 npm install -D vuepress-plugin-mathjax
  • 修改 .vuepress/config.js 文件

module.exports = {
    plugins: [
        [
            // 支持数学公式
            // https://vuepress.github.io/zh/plugins/mathjax/
            // npm install -D vuepress-plugin-mathjax
            'vuepress-plugin-mathjax',
            {}
        ]
    ]
}

• TaskList（插件）
  • 安装插件 npm install markdown-it-task-lists -D
  • 分别修改 .vuepress/config.js文件 和 .vuepress/styles/index.styl

module.exports = {
  markdown: {
    // 支持 task list
    // npm install markdown-it-task-lists -D
    // 除了这个还要在 .vuepress/styles/index.styl 中还要修改
    extendMarkdown: md => {
      md.use(require('markdown-it-task-lists'))
    }
  }
}

.contains-task-list LI
{
	list-style-type:none;
}

1.3. Markdown Front Matter 功能

• 概念：即 Markdown 文件最开头使用 ---包裹起来的内容，定义了标题、分类、标签、发布时间等一系列功能。

• 默认主题相关

  • 参考文档
  • 预定义参数：title/lang/description/layout/permalink/metaTitle/meta
    • 除了前三个，其他没见过
  • 默认主题参数：navbar/sidebar/prev/next/search/tags
    • 前5个都是用来设置功能开启与否
    • 最后一个可以优化内置搜索，也可以生成Tags界面（reco功能）

• Reco 相关

  • 参考文档
  • 相关参数：title/date/sidebar/categories/tags/keys/publish/sticky
    • 好像没什么要多介绍的，都是顾名思义。
    • sticky是置顶与否，keys是设置密码与否。

1.4. 更多功能

• 站内搜索
  • 来源：默认主题自带功能。
  • 具体使用参考文档
  • 功能：站内搜索，可通过文档tags优化搜索结果。
• 评论
  • 来源：reco集成插件Vssue
  • 功能：这是基本需求，想用内置的Vssue评论，即通过issue来保存评论内容
  • Vssue官网
  • 需要注意的是，如果使用Gitlab，需要将所有文章链接都添加到 callback url 中……
  • 不显示评论通过在front matter中添加 isShowComments: false实现。
• 加密
  • 来源：reco自带
  • 参考文档
  • 功能：全局加密（进入网站就需要输入密码，关闭标签后登录失效）、文章加密
• 最近更新时间
  • 来源：默认主题自带功能，必须使用git管理。
  • 效果不清楚，需要使用以下试试。
• 在网页上生成Edit this page连接
  • 来源：默认主题自带功能。
  • 功能：在页面中可直接进入对应的github/gitlab连接。

2. 进一步配置备忘

2.1. 配置文件相关

• vuepress官方参考文档
• reco参考文档
• 配置很多，没有一个个试过。
• TODO，都试一试。

2.2. 目录结构

• 参考文档
• 根目录下包含一个文件夹与package.json文件
  • 前者包含所有文档内容，一般名为docs，当然，可以改。一般里面有.vuepress和其他markdown页面。
  • 后者包含一些基础命令
• 目录位置（即基于docs的相对路径）与相对url的关系

Relatie Path	Page Routing
/README.md	/
/guide/README.md	/guide/
/config.md	/config.html

2.3. 静态资源

• 参考文档
• 作用：用来保存一些图片/js/css等，方便页面访问。
• 文件都保存在 .vuepress/config.js中。

2.4. 特殊页面

• 时间轴
  • 来源：reco附加功能。
  • 具体使用请参考文档。
  • 作用：生成一条时间线，展示发表论文的时间。该时间可自动生成。
• 标签与分类：0.x和1.x有不同
  • 第一步都相同，在普通文档的Front Matter中添加categories和tags信息。
  • 第二步，一个是新生成页面，指定FrontMatter信息，另一个是直接在配置文件中固定在导航栏中的位置。
    • 1.x文档
    • o.x文档
  • 采坑：使用1.x的方法时，如果config.js中nav的设置与blogConfig冲突（比如nav中定义了3个标签，blogConfig中配置的位置为1或2），那blogConfig中的配置无效。

3. 其他问题

3.1. 新项目构建流程

• 为了方便自己以后使用，建了一个项目： vuepress-reco-demo

• 第一步：安装nodejs，并新建一个文件夹，比如 vuepress-reco-demo

• 第二步：构建基本项目目录

  • 根目录下新建 package.json
  • 创建文件夹（名字随意），用于保存所有配置以及markdown文件。
    • 该文件夹中，有一个 .vuepress文件夹，用于保存vuepress的配置以及插件的配置，这个看vuepress的文档。
    • 其他的目录就是用来放markdown文件的。

• 第三步：通过命令行进入该文件夹，安装各种依赖

  • 安装 vuepress： npm install -D vuepress
  • 安装主题 reco： npm install vuepress-theme-reco --save-dev
  • 安装相关插件
    • 公式： npm install -D vuepress-plugin-mathjax
    • 图片缩放： npm install -D vuepress-plugin-medium-zoom
    • 支持 Markdown Task List： npm install markdown-it-task-lists -D

3.2. 侧边栏使用问题

• Reco 主题修改了一些默认主题侧边栏的功能，具体的可以参考官方文档。
• 大概总结下 reco 中的侧边栏：
  • 左侧侧边栏是默认主题提供的，而不是reco提供的；右侧侧边栏是reco主题提供的。
  • 文章内章节标题的显示：默认主题中，左侧侧边栏可以显示；reco主题中，左侧侧边栏不会显示，右侧侧边栏会显示。
  • 右侧侧边栏只用来显示文章内小标题，即目录。
• 默认主题中，front matter 中 sidebar: auto 的功能是自动添加文章章节标题到左侧侧边栏。很显然，这个功能在reco中无效了。
• 在front matter中添加 sidebar: false以及subSidebar: false，并不能隐藏侧边栏，原因未知。

3.3. 首页侧边栏隐藏的问题

• 由于上面提到过，sidebar: false以及subSidebar: false并不能隐藏侧边栏，那首页中也肯定有侧边栏……
• 解决的思路：
  • 首先，我觉得这应该是reco处理的问题，而不是用奇怪的方法解决这个问题……但现在作者可能没空处理，只要用一些奇怪的方法来解决。
  • 解决的思路是，使用vuepress提供的多个侧边栏。
  • 多个侧边栏提供的功能是：为不同的子目录提供不同的侧边栏内容。
  • 那只要首页与其他页面不在同一个子目录下，就能解决我们的问题。
• 具体实现：
  • 在docs目录下再建一个文件夹，比如还叫 docs。
  • 将除了首页README.md之外的其他markdown文件都放到这个文件夹中。
  • 在建立自定义侧边栏的时候，使用多个侧边栏的格式，即 sidebar: {'/docs/': [...]}

3.4. 评论插件 Vssue 的使用问题

• Vssue 提供了通过issue保存评论的功能，支持 Github/Gitlab/Gitee 等多个平台。

  • Vssue是我使用vuepress的主要原因，reco对vssue的支持比较好。
  • 我们需要全部运行在内网中，所以评论系统最好就是基于我们内部Gitlab的Issue。

• 实际使用中，除了Gitlab/Gitee的使用都存在同一个不可接受且无法处理的问题。

• 问题描述：

  • Vssue的实现其实是依靠 Github/Gitlab 等平台提供的各种API来处理的。Vssue的登录方式，其实使用了各平台的OAuth2功能。
  • Vssue中的理想的认证流程大概是：
    • 第一步：在某页的评论栏中点击选择登录。
    • 第二步：跳转到Github/Gitlab网站，访问OAuth2接口，实现认证。
    • 第三步：跳转返回第一步中的网页。
  • 在设置跳转返回的url，需要在Github/Gitlab的OAuth2的应用中手动设置：
    • 在Github中叫做 Authorization callback URL，支持设置的url以及所有子路径。
    • 在Gitlab中叫做 redirect uri，只支持设置的url。
  • 换句话说，当使用Gitlab的时候，如果某个页面的url并没有手动添加到redirect uri中，那在这个页面就不能进行OAuth2认证（即不能进行登录操作，但如果之前已经登录了，只是要评论，还是能做到的）。
  • 这个问题已经在多个地方提到了
    • issue#58
    • Vssue官方文档-支持的代码托管平台

• 解决方案一：最笨的办法

  • 将每个url都手动添加到redirect uri中。
  • 先写个脚本获取所有url，手动复制一下。
  • 如果文件增加速率不高，一周搞一次，也差不多了……

• 解决方案二 - 自动跳转

  • 目前 Vssue 已有相关PR，但作者还未处理，给Vssue开发者发了个邮件，希望大佬有空能处理下。
  • 首先问一个问题，为什么Gitlab/Gitee会这么设计 redirect uri 呢？我猜是安全问题……
  • 解决思路：将原页面url作为OAuth2的一个参数，所有OAuth2认证都跳转到同一个callback url，当OAuth2认证结束进入callback url后，在callback url页面通过保留的原页面url进行跳转。
  • 菜鸡的临时解决方法
    • 直接修改vuepress项目中的 node_modules/@vssue/api-gitlab-v4/lib/index.js文件。
    • 修改内容从PR#101中找，大概就是修改了redirectAuth和handleAuth两个函数。

3.5. 手动创建侧边栏比较麻烦

• 问题描述：为了在侧边栏中显示新添加的文章，需要在每次添加文章后，手动修改config.js文件。
  • 如果只是一个人开发，那还好。虽然麻烦，但至少自己捣鼓的配置文件，也知道怎么处理。
  • 如果多人开发，那就要求每个人都懂的这个内容，比较麻烦。
  • 有一个ISSUE对应本问题，虽然close了，但其实并没有解决……
• 解决方案一 - 插件1自动生成
  • 使用 vuepress-plugin-auto-sidebar 插件，可自动生成左侧侧边栏。
  • 但存在一个问题：这个插件只能生成同一个文件夹中所有文件的侧边栏，不能生成多个文件夹的内容。
  • 原因是可以从 ISSUE#13中找到，作者认为：

如果以增加子文件夹来划分那就产生了新的问题：不同的目录在多少深度（几层子文件夹）时才划分为分组，配置起来感觉也并不直观。

这一块如果很多可以考虑下 官网 nav 的分组功能。

• 解决方案二 - 插件2自动生成

  • 使用 vuepress-bar 插件，可自动生成侧边栏以及导航栏。
  • 不生成导航栏只生成侧边栏的方法运行成功，但存在首页侧边栏无法隐藏的问题。
  • 导航栏、侧边栏同时生成的方法运行不成功，但就算成功，应该也存在首页侧边栏无法隐藏的问题。

• 解决方法三 - 直接添加js代码

  • ISSUE#13里面提到的方法，来源于这里。
  • 大概原理就是，获取某个文件夹内的所有md文件，作为children的内容。
  • 不能处理多级目录的问题。
  • 不用安装插件，如果不需要多级目录，这是一个好办法。
  • 最好的办法还是自己会写js代码……而我不想花时间

3.6. 文档模式下的标签（Tag）与分类（Categories）

• 个人觉得，文档模式的默认配置下，两者的功能几乎一样。

• 两者都有的功能：

  • 都能自动生成特殊页面。
  • 两者都只能进行一级分类，不能实现多级分类。

• 标签有、分类没有的功能：

  • 在每篇文章中，显示标签类别（不会显示分类类别）

• 标签没有、分类有的功能：

  • 导航栏中，分类标签有子分类的下拉菜单，标签没有下拉菜单。