TniAsu
TniAsu
文章10
标签16
分类2
Vuepress

Vuepress

一个基于 Vue 的文档系统。

Vuepress

前些日子通过搭建 Vuepress ,也把博客上的一些文章搬到了 Vuepress 上面,博客用来记录杂事, vuepress 用来写笔记,分工明确有条不絮,且同样是静态文件生成器,搭建起来几乎没有成本,确实是值得去研究一下的

而 vuepress 的搭建难易程度在我看来要要比 hexo 麻烦不少,个人觉得最难受的一点就是侧边栏的配置以及需要自行创建目录这两点,

而解决这两点的方法我在下文也会提到。

在这里先说一下,vuepress 搭建起来并不难,只是要麻烦一点,本人没有一点 vue.js 以及 JavaScript 的基础,仍然是把它搭建好了,美观程度与易用性也毫不逊色,是一个非常不错的选择,简单明了一点:真的是有手就行!

搭建 vuepress 的方法我也不详细讲了,使用 yarn 和 npm 都可以,但是 安装 node 的时候在 linux 下还是最好使用 nvm 诸如此类的 node 管理器来安装,出现问题的几率也不会太大。

关于开篇提到的两个问题

  1. 侧边栏

    Vuepress 的非自动生成的侧边栏是全局的那种侧边栏,这也是 Vuepress 设计的初衷:为了爽爽地撸文档。如果你需要讲所有文章都目录都显示在侧边栏,那么你当然可以按照官方提供的默认方法来进行 config. 的配置,但是如果是做个人博客,或者是门类比较多的文档项目,全局侧边栏就可能并不适合自己了,如果你只想显示某一类或某一篇的话,你有一下解决方法:

    1. 新建 README.md 文件,这个 README.md 文件并不是初始的在 docs/ 目录下的 README.md 文件,而实需要你将你所写的某一类文章单独放在一个文件夹下(最好是这样,方便索引),然后 README.md 文件的内容照着 docs/ 下的那个抄一下 ymal 就好了,其余的内容自己写就行,然后每写一篇该类别的文章就在 README.md 里加一下就可以了
    2. 切换主题,不使用默认主题,这里推荐使用 reco 主题,主题相对于默认主题添加了时间轴、分类,标签等。因为添加了分类,使用了这款主题的 Vuepress 就非常适合做门类较多的文档或者博客了。起始页的 README.md 中按钮的链接可以直接改为分类页面,方便文章的索引,然后侧边栏目录使用每个页面自动生成就可以了。
  2. 目录

    1. 官方提供的目录结构如下
      ├── docs
      │   ├── .vuepress (可选的)
      │   │   ├── components (可选的)
      │   │   ├── theme (可选的)
      │   │   │   └── Layout.vue
      │   │   ├── public (可选的)
      │   │   ├── styles (可选的)
      │   │   │   ├── index.styl
      │   │   │   └── palette.styl
      │   │   ├── templates (可选的, 谨慎配置)
      │   │   │   ├── dev.html
      │   │   │   └── ssr.html
      │   │   ├── config.js (可选的)
      │   │   └── enhanceApp.js (可选的)
      │   │ 
      │   ├── README.md
      │   ├── guide
      │   │   └── README.md
      │   └── config.md
      │ 
      └── package.json

仅仅是把 vuepress 拿来当博客的话,其实根本不用这么麻烦,我们可以直接从 GitHub 上 clone 下来一些实例网站的代码,他们一般都会创建好必要的目录,而我们只需要根据自己的需求去修改即可。有需求的话可以参考我的自己的 Vuepress ,直接克隆到本地,根据需求添加删改即可,这样对于不想在配置上花费太多时间的人来说是一个不错的选择。

一些配置与踩过的坑

数学公式渲染(KATEX):

搭建 Vuepress 的初衷就是因为 hexo 的数学公式引入的外部链接访问速度有点慢,导致对其渲染速度也慢,而且所谓按需加载其实并没有做到,而是全站都会进行对外部链接的请求,这样就导致拖累了整站性能,而且我也懒得去本地化了……

而 Vuepress 正好是一个适合做技术文档的程序,数学公式这块也肯定有支持,只需要安装 markdown-it-katex 插件即可。

$ yarn add markdown-it-katex -D

$ npm install markdown-it-katex --save

接着在配置文件 config.js 中进行编辑

$ vim vuepress根目录/docs/.vuepress/config.js

修改或添加以下内容

markdown: {
        extendMarkdown: md => {
            md.set({
                html: true
            })
            md.use(require('markdown-it-katex'))
        }
    },
    head: [
        ['link', {
            rel: 'stylesheet',
            href: 'https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.7.1/katex.min.css'
        }],
        ['link', {
            rel: "stylesheet",
            href: "https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/2.10.0/github-markdown.min.css"
        }]
    ]

然后运行重新构建查看是否渲染数学公式即可。

一些报错以及无法渲染的问题

五一假期我在学习 Python ,记过笔记之后提交到 GitHub ,在 zeit 构建的时候却报错了

通过排查发现,是因为 vuepress 中添加了错误的 html 标签。

原来是在搬运文章的时候,之前 hexo 的文章直接复制过来的时候,似乎是因为渲染器的不同,导致数学公式两旁的 $$ 渲染成了 <script type="math/tex; mode=display"><script> ,而 vuepress 的渲染器 markdown-it 无法识别type="math/tex" 这条,所以就导致了报错。删掉改成 $$ 即可。

不仅如此,

当我填写这些内容的时候,也是无法进行渲染的。

于是我只能逐字排除,最终找到了问题所在,那就是 <a>.<b>()<a><b>

兴许是 markdown-it 的问题,将这条编码风格(所有的以<> 尖括号为开头结尾的)认为是 html 标签,结果导致无法渲染吧,解决问题的方法也很简单,在外面套一个 “ ` “ (accent) 即可。当然你也可以添加其他渲染器可以识别并优先渲染的符号,将尖括号嵌套到内部不优先被渲染即可。