第一次被合并 PR!

今天,Kiyoshi 发了人生中第一条 Pull Request!因为在使用 Molunerfinn 大佬的 Melody 主题,遇到了 LaTex 总会有的问题,也就是插入的公式如果太长,它会超过整个页面的宽度,让页面变得丑陋无比。

丑陋的博客
所以 Kiyoshi 想要修复这个小问题并向主题 Contribute!

问题分析

根据以前用 WordPress 的经验,同样的在 MathJax 中出现的问题可以直接在渲染出的数学公式的 Wrapper 上加上滚动条,让它保持该有的长度。为了美观,我们也可以把滚动条给隐藏,依旧保留其滚动的功能。想要实现这个功能,首先要学(suí)习(biàn)一(fān)下(fān)Hexo 主题的目录结构,定位需要修改的文件,接着魔改实现功能就行啦。

实现方法

根据 Hexo 生成的 HTML 来看,渲染出来的公式是由几个 span 包裹住的。
HTML 结构
初步构思是可以通过 CSS 选择 span.katex-html 并进行滚动条的添加。由于 KaTex 的书写是在 Post 类页面中,所以可以更改 Post 的 Stylus 文件来修改样式。

post.styl 中加入如下 Stylus 代码即可初步实现隐藏滚动条的可滚动 span。

1
2
3
4
span.katex-html
overflow: auto
&::-webkit-scrollbar
display: none

保存提交

在实现后,Kiyoshi 直接 commit 并提交了更改到自己 fork 的仓库中,还直接对原仓库发起了 PR。由于 Kiyoshi 是菜鸡,被大佬鼓励了一下并提了建议:

@upupming

  1. 行内公式无需处理,根据 KaTeX/KaTeX#327 已经会自动换行。
  2. 行间公式在 katex-display 外部加一个 div 就好了。
  3. 滚动条可以做配置项让用户自己设置

根据以上建议,整理出要做的事情如下:

  1. 给配置文件 melody.yml 加配置项以设置隐藏滚动条与否
  2. 修改 post.styl 以根据配置项来隐藏滚动条
  3. span.katex-display 外加 div 包裹公式内容以便于修改
  4. 修改 post.styl 以选中添加的 div

每一步问题都不大,但是由于 Kiyoshi 开发经验有限,而且几乎还没碰过 Node,所以第三步确实不知道怎么做了。于是在已经关闭的第一条 PR 中问了大佬,并得到了回复:

@Molunerfinn

@Kiyo5hi 外面加 div 可以通过 JS 来加。可以参考代码区 复制代码 按钮的实现:
https://github.com/Molunerfinn/hexo-theme-melody/blob/dev/source/js/copy.js#L3-L7

于是 Kiyoshi 懂了个大概地准备好继续改东西啦。

回炉重造

首先 Kiyoshi 在 melody.yml 中添加了配置项:

1
2
3
4
5
katex:
enable: false
cdn:
css: https://cdn.jsdelivr.net/npm/katex@latest/dist/katex.min.css
hide_scrollbar: true

有了这个配置项就可以在 Stylus 中直接获取其值并决定是否隐藏滚动条啦。也就是说,我们只需要在原来的代码上添加一个判断就可以啦:

1
2
3
4
5
.katex-html
overflow: auto
if hexo-config("katex") && hexo-config("katex.hide_scrollbar")
&::-webkit-scrollbar
display: none

现在主题就会根据配置是否允许滚动条显示而渲染出 CSS 文件了。
最后一件事情,也就是在 span.katex-display 外面套 div 就比较麻烦了,但是也没有那么麻烦。根据 @Molunerfinn 大佬给的参考来看,我需要在创建一个 .js 文件并在里面写向 span 外层加包装的代码,并在 .styl 文件中引用它。
根据 Kiyoshi 再次对目录进行的学(luàn)习(fān)来看,可以在 /melody/source/js/ 目录下创建 katex.js 文件并在 /melody/layout/includes/third-party/katex.pug 中引用。

katex.js:

1
2
3
$(function () {
$('span.katex-display').wrap('<div class="katex-wrap"></div>')
})

layout/includes/third-party/katex.pug:

1
2
3
4
5
6
link(rel="stylesheet" type="text/css" href=theme.katex.cdn.css)
script(src='https://cdn.jsdelivr.net/npm/katex-copytex@latest/dist/katex-copytex.min.js')
link(rel="stylesheet" type="text/css" href='https://cdn.jsdelivr.net/npm/katex-copytex@latest/dist/katex-copytex.min.css')
link(rel="stylesheet" type="text/css" href='https://cdn.jsdelivr.net/npm/katex-copytex@latest/dist/katex-copytex.min.css')
//- New Line
script(src=url_for('/js/katex.js'))

接着,再改一改 Stylus 的选择器就行啦。

source/css/_layout/post.styl:

1
2
3
4
5
.katex-wrap
overflow: auto
if hexo-config("katex") && hexo-config("katex.hide_scrollbar")
&::-webkit-scrollbar
display: none

这样我们的任务就大功告成啦!
隐藏 Scrollbar 的效果

再次提交

接着 Kiyoshi 再次提交了 PR,被作者 Merge 啦。

总结

Kiyoshi 是个彩笔啊。

End - of - File

文章作者: Kiyoshi
文章链接: https://blog.k1yoshi.com/article/the-first-pull-request/
版权声明: 本博客所有文章除特别声明外,均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来自 Kiyoshi's Blog