前言

BookStack作为一个非常好用的可自托管的用于文档以及Wiki储存的软件，常常被用于管理与储存大量文献。但是，默认情况下，他在显示文本内容的时候，不会渲染文本中的Latex公式（如图1）。这篇文章会介绍一种无需修改BookStack源码即可给他增加Latex公式渲染功能的方法。

实现思路

Bookstack提供了自定义HTML头部内容的功能，利用这个功能能够添加自定义的HTML代码到实例的每一个页面之中，我们可以在这里添加自定义的Js脚本，从而手动给BookStack添加Latex渲染功能。

操作步骤

首先使用管理员账号登录BookStack，点击右上角的设置，再点击个性化，出来的界面如下图2

打开后划，将界面滑动到最底下，可以看到自定义HTML头部内容的板块，就是图3中红圈圈出的部分。

在下面添加下面的脚本，保存设置，刷新即可。

备注：下面的脚本调用了储存于我服务器的Katex.js，Katex.js相比其他的渲染方案有速度快稳定的优势，但是请不要大规模的调用储存在我服务器的这个js（仅能用于个人的小规模使用），如果有需求，您可以将其替换为jsdeliver提供的Katax.js。

<link rel="stylesheet" href="https://static.q2019.com/vendor/katex/katex.min.css">
<script defer src="https://static.q2019.com/vendor/katex/katex.min.js"></script>
<script defer src="https://static.q2019.com/vendor/katex/contrib/auto-render.min.js"></script>
<script>
  document.addEventListener("DOMContentLoaded", function() {
    if (window.renderMathInElement) {
      renderMathInElement(document.body, {
        delimiters: [
          { left: "$$",  right: "$$",  display: true  },
          { left: "$",   right: "$",   display: false },
          { left: "\\[", right: "\\]", display: true  },
          { left: "\\(", right: "\\)", display: false }
        ],
        throwOnError: false,
        // 可选：避免渲染代码块里的文本
        ignoredTags: ["script","noscript","style","textarea","pre","code"]
      });
    }
  });
</script>

保存之后，刷新有Latex公式的界面，可以看到Latex会被正确渲染了，如图4所示

常见问题

问题1：为什么实时编辑时候公式不会渲染？

答：BookStack在编辑的时候（无论使用的是所见即所得编辑器还是Markdown编辑器）是不会加载我们刚刚添加的Latex渲染逻辑，所以公式不会被渲染。

问题2：为什么有些情况下公式不会被正确渲染？

答：刚刚的我们加的渲染逻辑仅仅只能对类似$E = mc^2$这个样子的行内公式，或者像$$f(x) = 3x^3 - 4x^2 + 3x + 4 $$ 这个样子的两个 $$ 标识都在一行的行间Latex公式有效。因为BookStack对于多行的文本，会自动拆成多段，导致我们刚刚设计的脚本无法正确的对Latex公式进行渲染。而对于类似[\f(x) = 9x^2-8x+3\] 的公式，无论是否多行，由于BookStack的编辑器会对 “\”这个字符进行转义，导致无法正确渲染。个人推荐在BookStack中使用$E = mc^2$ 这样的方式进行公式的撰写。

脚注

https://www.bookstackapp.com/hacks/mathjax-tex，这是BookStack官方关于渲染公式的一个小方案，但是使用的是MathJax方案，本文使用的是Katex方案。