Written by 冥郡
on 

记一次 Prettydoc 的改造

声明

本文的出发点并不是鼓励去“剽窃” Prettydoc 包的成果，而是给一种比较小代价改造模板的流程介绍。

写文章有两种观点，一种叫天下文章一大抄，一种叫站在巨人的肩上可以看得更远。前者在抄袭的道路上越走越远，后者推陈出新发明出更多很有意思的事。(这里希望夹带一些私货，仅之前在统计之都发表了一篇关于 R Markdown 的文章，却发现各种平台未经允许直接转载，甚至有的转载不附加链接，这里必须澄清一点，不是在我个人博客或是统计之都看到我写的统计文章都属于抄袭，请联系本人，将采用发律手段解决。)

本文希望基于一个创作 R Markdown文档的例子 (在电脑上看效果比较好)，对 Prettydoc 进行分析。读者可以根据自己的程度和需求，选择是停留在对模板的颜色、字体大小的程度，或是往前走一点——自己发明创造，进行阅读。

改造原理及意义

意义

其实自定义一份模板起初没什么特殊含义，但最近深感创作侵权违法成本太低，举证困难，却苦于没有方法。自定义模板可以设置水印，可以设置选择失效，防止直接复制粘贴。虽然对于会写网页的人来说，这样的设防约等于没设，但是增加一些抄袭成本还是挺有意义的。

初步尝试的失败

最起初的想法是自己写一个模板，然后不断调 CSS 和 HTML 的位置和情况，甚至可以不依托 Prettydoc 定义出自己的模板。但毕竟自己不是前端工程师，没有如此深厚的前端功力。之后的想法是利用已经写好的博客模板，直接迁移到 Prettydoc 上，我自身的博客在 Jekyll 的基础上进行开发，也改造过一些模板，于是从 Jekyll 模板 http://jekyllthemes.org/ 网站上试图下载一些下来，并进行修改。最后下载下来的模板由于其自身依赖的复杂性，十改九失败。即使改造成功，也存在着没调整好标签定位所导致网页变形的情况。 不得不承认，在自己的前端水平限制下，无法在较短的时间内完成如此的工程。最后还是退而求其次，从原有的 Prettydoc 模板出发，进行改动。即使是 Prettydoc 的模板，起初也是 github 中各种高手实现的，邱怡轩做的 Prettydoc 也是将这些模板综合起来，形成了一套完整的生成报告的流程。

改造所需要的知识

改造过程中最不需要的就是 R 的知识，这可能是很少有人愿意去改的原因，但其实整个过程不难。 一般的静态网页可以分为三个部分，分别用三种语言完成。这三个部分可以对应于人骨骼、皮囊和以血液为代表的动力系统。骨骼对应的是 HTML 所写的文本，HTML的知识可以自行搜索，概括的说就是文本及其定位。皮囊对应的是 CSS 给网页带来的层层渲染，最简单的例如颜色、字体、位置等。血液之类的动力其来源是 JavaScript ，其作用是时整个网页“动”起来，或者是可以相应某些动作。

回到Prettydoc生成的文档，自定义的第一步还是需要从 R Markdown 的链接生成命令开始，下面截取了一小部分：

/.../pandoc/pandoc ... temp.utf8.md ... --output temp.html ... --template /.../prettydoc/resources/templates/cayman.html ... --css temp_files/style.css

这里解读编译命令需要参考上一篇文章。为了照顾读者的关注点，我将不重要的部分都用三个点代替。

而模板所在的位置，就在上面 prettydoc 的 templates 文件夹下，即--template 后面的路径。

找到路径后发现往上翻一下，有四个文件夹，css、fonts、images、templates，注意没有 js 的文件夹，但并不代表无法将js链接进模板中。最朴素的想法是，将 js 代码直接写到 html 里，虽然这并不是一种很好的编程风格。可以先从原理出发，把这些问题一一记下，之后再一一解决。

  • 问题一 如何单独写自定义的js并将其引用？
  • 问题二 到底prettydoc是如何将这些文件链接起来形成文档的？

先解决第二个问题，观察源 R Markdown文件所在的目录，然后点击 Knitr 生成 HTML 的过程可以发现，生成时会先产生一个临时文件夹和一个临时的Markdown文件，所以原理其实也就是把需要的文件都链接起来，然后利用pandoc把该转变的语言都转变了，再删除临时文件即可。整个事件都在底层完成了。链接的是什么文件呢？再回到模板的目录，不难发现，也就五个模板，对应五种主题，由于网页一定需要 CSS 文件，所以再看 CSS 文件夹，除了字体文件夹，其余的十个CSS文件分别对应五种主题。

根据面向对象的思想(类似于多态)，不可能会将主题写死，这样不利于邱怡轩哪天心血来潮的时候，想自己加个主题还要重新编译自己的 R 包。基于这样的猜想，自定义主题就是复制一下他写的 HTML 文件和 CSS 文件，按照一样的形式，一对二，并将名字改成一致的，即可“抄袭”原有的模板，开始自定义主题。 这里可以说是整个改造 Prettydoc 包能推进下去的核心原理。

这时候，再仔细把每个主题的HTML打开，很容易发现，其中的内容居然是完全一样的！这给改造节约了很多时间。改来改去，用的标签都是一样且在HTML中写好的，会变的无非就是CSS中的样式而已。CSS变来变去，骨骼是不变的，无非是对应标题的位置放在左边还是右边的区别，配色好不好看，字体好不好看的区别而已。

但这里的改造不一定就遵循原作的风格，骨骼一样可以变，也就是可以增加新的标签去记录信息，例如可以在左上角建立一个统计功能，例子中的左上角就是对文档中漂浮点的统计。

正式改造

下面以 Cayman 为例，改造一下模板。选择改这个模板的原因很朴素，Cayman的 CSS 代码最短，改造起来最容易，其造型也比较容易为人接受。

改造模板的第一步是将原有的 HTML文件和 CSS 文件都复制一下，然后重新命名为自己喜欢的名字。改完名字后，做一个测试，将 yaml 中的 theme 后面的主题换成自己改的名字，之后生成文档(做测试的时候最好不要复制修改命名 Cayman ，因为默认找不到主题文件时，会使用 Cayman 作为主题，这样就不确定复制是否有效)

假定读者都找到了模板的位置，并进行了复制和改名，生成也成功了，下面来了第三个问题。

  • 问题三 CSS的代码还是茫茫多，如何才能改？

其实这个问题对会使用 CSS 的人来说应该不是问题，但毕竟不是人人都会，这里可以简单提一下，详细理解还是需要参考讲解 CSS 的网站，本文无法穷尽。一般标签有两种方式定位，一种是 class，一种是 id。在 CSS 中定义 class 的属性，会对所有带同一个class名字的标签都进行渲染。id 是唯一标识，仅会渲染唯一的带有那个 id 的标签。也就是说 CSS 中一个个的大括号中的就是定义着某个类或者某个 id 的属性，找到想改的标签下对应的属性做修改即可。

不写网页的人对标签位置的寻找也许不太清楚。寻找内容所对应的标签其实很简单。利用浏览器右键检查，就会打开开发者工具，自动定位到鼠标所在位置的标签名字。

一般正常人想修改的就是背景颜色和字体颜色而已。检查后可以根据开发者工具中 style 颜色的具体情况，返回到 CSS 文件中，修改对应的颜色即可。

  • 问题四 有两个CSS文件，到底修改哪一个？

其实两个CSS文件的内容是一致的，但实际上R Markdown用的是\*.min.css。原因也可以深究一下，其实是和链接的过程有关，\*.css的文件含有多余的回车分号等不必要的信息，虽然阅读起来比较方便。最后生成的文档就是一个简单的 HTML 文件，由于这些符号冗余的存在，会使得文件变得 臃肿，所以这里链接的是\*.min.css。

下面就 Cayman 简单修改一下：

最醒目的颜色是 Cayman 最上面的一长条的颜色框，其颜色是渐变的，寻找一下渐变并带有 head 的属性，可以找到：

.page-header {
  color: #fff;
  text-align: center;
  background-color: #159957;
  background-image: linear-gradient(120deg, #155799, #159957);
  padding: 1.5rem 2rem;
}

渐变色显然就是background-image这里的颜色。不想随便试颜色最好的方法是上网去找喜欢的配色方案，之后可以得到以下 Head:

简单调头部的背景色

除此以外，还可以修改渐变颜色的方向，也可以将背景换成图片。但这些都仅仅是限制于表面的修改，最多能让文档的展示从表面上看上去与众不同。更深层次的修改，也就是添加 JavaScript 才是让报告更上一个台阶的关键。也是下面要谈的重点。

让文档动起来

要引入 JavaScript 就必须先回答问题一，最朴素的想法是在模板外的目录下创建 js 文件夹，按照 CSS 文件的引用情况，有可能会自动将 js 文件夹复制过去，但实际上，这样的想法还是太天真。只要在生成 temp_files 文件夹时，将其拖拽出原来的文件夹(只有在R Markdown将临时文件删除前拖出去才能看)，就可以发现，在生成临时文件时，并没有生成 js 文件夹，自然直接放 js 文件夹不可行。转念再想，至少复制了 images 文件夹下的所有东西，那么复制 images 文件夹不也可以吗?基于这个朴素的想法，和路径的尝试，在将 script.js 文件放进 images 文件夹后，在 HTML 中的引用路径就可以如下：

<script  src="temp_files/images/script.js"></script>

引用其实只要找到路径即可，若是临时的，特殊的不属于特定模板的 js 文件，也可以用更简单的方法引用，即在 R Markdown 文件所在目录下放置 script.js 文件，那么引用的路径就可以是：

<script  src="script.js"></script>

或者是

<script  src="./script.js"></script>

这些都是比较取巧的解决方法，更为合理的解决方案还是应该从制作这个包的过程中，就将这个需求考虑进去。

起初可以加 JavaScript 之后，我停留在比较低级的阶段——无非加点水印之类的，知道后来在读 Graph Embedding 代码时，发现了一个有意思的博客https://zhuo931077127.github.io/。其背景的粒子效果特别炫酷，于是有了据为己有的贪念。上网一搜粒子动画，就找到了一个制作此类动画的 JavaScript 库——https://github.com/VincentGarreau/particles.js。

之后的制作过程也就比较简单了，在https://codepen.io/VincentGarreau/pen/pnlso上，先编辑好代码，然后将 HTML 、 CSS 、 JavaScript 的部分加到相应的部分中。例如 HTML 部分：

<div id="particles-js">
<section class="main-content" id="scro">
$body$
<span class="js-count-particles">--</span>
</section>
</div>

其中，JavaScript 部分直接生成 script.js 文件，并在 HTML 中添加 particle.min.js 等的引用。 CSS 部分则稍微需要一些调整，这也是困扰我两天的问题。

  • 问题五 canvas 和 div 同时存在时，会“井水不犯河水”，如何做到github上那位用户的效果？
  • 问题六 生成的canvas太短，仅够遮住第一页，但section标签里的内容太长怎么办？

问题五很好解决，将其中的一个position改成固定即可。问题六确实困扰了我很久，但在反复观察别人的博客后，领悟到了一句话：风动还是云动？运动是相对的。起初我想的都是怎么让 canvas 不断填充div，哪怕复制重复也可以，但效果并不好。其实博客中，根本是 canvas 没有动，动的是div标签。那么解决方法就很简单了，即给section加上一个新id(参看上一个代码段，section有一个id叫scro),并在 CSS 中增加：

#scro{
overflow-y:scroll
}
::-webkit-scrollbar {
display: none;
}

其作用是让这个 div 中的内容滚动播放。但由于 canvas 的位置是 absolute ，canvas就不会随滚轮向下走。后面的 display: none;是不显示滚轮。

最后可以得到的效果可以参看例子。

此外，利用canvas写报告还是存在一个硬伤，在打印pdf时，canvas是不能随着文档的展开而展开的，这也是需要不断探索解决方案的，动静之间，不可兼得。

但用 JavaScript 添加动画并不一定要 canvas。这里是想暗示，所有用 JavaScript 可以实现的效果都可以加到文档里。当把这些文档抽离出来，形成类似电子相册的东西时，就得到了博客。改造 Prettydoc 的一切技巧和解决思路都可以原模原样搬到自己的博客上。站在我的肩膀上，希望读者能创造出更精彩的模板，并跳出 Prettydoc 的框架。我可以假想有这样一个 R 包，以拖拽、绘画的方式在网页服务器上定制自己的模板，再通过命令反过来将生成的模板添加到这个 R 包中。那么毫无疑问 R Markdown 会绽放出更多不寻常的可能性。

小结

有时候并不是能力做不到，在互联网的帮助下，基本有问题就能找到方法解决，只是方法的好坏而已。探索时最大的难题是没有想法，失去了灵感，做的工作也就是如工匠般的简单搬运。直接改 Prettydoc 的文件有违我的本意，虽然这是最容易自定义的方法。其实修改一个包没有什么难的，难的是能搭建起这个框架，让我能在其中修改。整个修改过程只是心血来潮地简单尝试，还有很多可以尝试的空间。JavaScript 可以加的动画无穷无尽，但有时我不得不反省，脱离了文档内容，而一味追求外观的酷炫是否南辕北辙？添加这样的动画，或许没有一开始时，简单地在文档中加水印和加反复制粘贴代码来的有意义。

参考资料