Vuepress & Reco主题备忘

最新推荐文章于 2024-09-17 20:00:00 发布

清欢守护者

最新推荐文章于 2024-09-17 20:00:00 发布

阅读量2.6k

点赞数 7

分类专栏：工具文章标签： vuepress 静态网站生成工具 sitegenerating vue

本文链接：https://blog.csdn.net/irving512/article/details/109377495

版权

工具专栏收录该内容

19 篇文章 3 订阅

订阅专栏

文章目录

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代码……而我不想花时间