数学公式如何渲染？解决pandoc+mathjax方案下的一些Bug

yngcy2024-10-232024-10-26

写在前面

数学公式的渲染教程可以参考 @yyyz。

下面是我遇到的问题和解决方案。

问题描述

本地调试时渲染正常，行内公式与正文之间的空格被保留。且使用 hexo g 生成的 public 文件中，文章行内公式左右的的空格也能正常显示。

但是服务器上空格却没有正常显示。

解决过程

既然本地显示是正常的，所以考虑应该是 GitHub Actions 的问题。

因为采用的是 后端渲染 的方式，也就是问题出在生成 public 文件的过程中。我们是采用 Github Actions 工作流来部署博客的，因此推测可能是版本不一致的问题。本地 Pandoc 的版本是 3.5，而在工作流中的版本是 2.14。

因此，我尝试在 GitHub Actions 中安装 Pandoc 3。

1 2	- name: Setup pandoc uses: nikeee/setup-pandoc@v1

但是好像还是不行……那就用最蠢的办法，本地跑一遍工作流！

1
2
3

hexo clean
hexo generate
gulp

果然空格被吞了，那么真相就只有一个了，就是 gulp！

import gulp from "gulp";
import cleanCSS from "gulp-clean-css";
import htmlmin from "gulp-htmlmin";
import htmlclean from "gulp-htmlclean";
import workbox from "workbox-build";
import fontmin from "gulp-fontmin";

// 若使用babel压缩js，则取消下方注释，并注释terser的代码
// var uglify = require('gulp-uglify');
// var babel = require('gulp-babel');

// 若使用terser压缩js
import terser from "gulp-terser";

//pwa
gulp.task("generate-service-worker", () => {
    return workbox.injectManifest({
        swSrc: "./sw-template.js",
        swDest: "./public/sw.js",
        globDirectory: "./public",
        globPatterns: [
            // 缓存所有以下类型的文件，极端不推荐
            // "**/*.{html,css,js,json,woff2,xml}"
            // 推荐只缓存404，主页和主要样式和脚本。
            "404.html",
            "index.html",
            "js/main.js",
            "css/index.css",
        ],
        modifyURLPrefix: {
            "": "./",
        },
    });
});

//minify js babel
// 若使用babel压缩js，则取消下方注释，并注释terser的代码
// gulp.task('compress', () =>
//   gulp.src(['./public/**/*.js', '!./public/**/*.min.js'])
// 		.pipe(babel({
// 			presets: ['@babel/preset-env']
// 		}))
//     .pipe(uglify().on('error', function(e){
//       console.log(e);
//     }))
// 		.pipe(gulp.dest('./public'))
// );

// minify js - gulp-tester
// 若使用terser压缩js
gulp.task("compress", () =>
    gulp
        .src([
            "./public/**/*.js",
            "!./public/**/*.min.js",
            "!./public/js/custom/galmenu.js",
            "!./public/js/custom/gitcalendar.js",
        ])
        .pipe(terser())
        .pipe(gulp.dest("./public"))
);

//css
gulp.task("minify-css", () => {
    return gulp
        .src("./public/**/*.css")
        .pipe(
            cleanCSS({
                compatibility: "ie11",
            })
        )
        .pipe(gulp.dest("./public"));
});

// 压缩 public 目录内 html
gulp.task("minify-html", () => {
    return gulp
        .src("./public/**/*.html")
        .pipe(htmlclean())
        .pipe(
            htmlmin({
                removeComments: true, //清除 HTML 註释
                collapseWhitespace: true, //压缩 HTML
                collapseBooleanAttributes: true, //省略布尔属性的值 <input checked="true"/> ==> <input />
                removeEmptyAttributes: true, //删除所有空格作属性值 <input id="" /> ==> <input />
                removeScriptTypeAttributes: true, //删除 <script> 的 type="text/javascript"
                removeStyleLinkTypeAttributes: true, //删除 <style> 和 <link> 的 type="text/css"
                minifyJS: true, //压缩页面 JS
                minifyCSS: true, //压缩页面 CSS
                minifyURLs: true,
            })
        )
        .pipe(gulp.dest("./public"));
});

//压缩字体
function minifyFont(text, cb) {
    gulp
        .src("./public/fonts/*.ttf") //原字体所在目录
        .pipe(
            fontmin({
                text: text,
            })
        )
        .pipe(gulp.dest("./public/fontsdest/")) //压缩后的输出目录
        .on("end", cb);
}

gulp.task("mini-font", cb => {
    var buffers = [];
    gulp
        .src(["./public/**/*.html"]) //HTML文件所在目录请根据自身情况修改
        .on("data", function (file) {
            buffers.push(file.contents);
        })
        .on("end", function () {
            var text = Buffer.concat(buffers).toString("utf-8");
            minifyFont(text, cb);
        });
});

// 执行 gulp 命令时执行的任务
gulp.task(
    "default",
    gulp.series("generate-service-worker", gulp.parallel("compress", "minify-html", "minify-css", "mini-font"))
);

在 guipfile 文件中，collapseWhitespace: true 会去掉空格以此压缩文件大小。而生成的 HTML 文件中，因为公式是以元素的方式嵌入到文本中的，因此 文本末空格被认为是多余的空格而被压缩。

我尝试了禁用该选项，但是并不能达到预期效果。如下图所示，空格还是被删了一个。

在 htmlmin 中 ignoreCustomFragments 支持正则表达式保留空格，我们想要保留数学公式前后的空格，通过查看源代码，发现元素是 <span class="math inline">...</span>。修改后代码如下所示：

...
.pipe(
    htmlmin({
        removeComments: true, // 清除 HTML 注释
        collapseWhitespace: true, // 压缩 HTML
        collapseBooleanAttributes: true, // 省略布尔属性的值 <input checked="true"/> ==> <input />
        removeEmptyAttributes: true, // 删除所有空格作属性值 <input id="" /> ==> <input />
        removeScriptTypeAttributes: true, // 删除 <script> 的 type="text/javascript"
        removeStyleLinkTypeAttributes: true, // 删除 <style> 和 <link> 的 type="text/css"
        minifyJS: true, // 压缩页面 JS
        minifyCSS: true, // 压缩页面 CSS
        minifyURLs: true,
        ignoreCustomFragments: [
            /(\s*<span class="math inline">.*?<\/span>\s*)/gi // 匹配并保留 <span class="math inline"> 前后的空格
        ],
    })
)
...

执行后发现效果还是不如预期，因为 htmlclean() 删除了行末的空格，因此删除这个即可，完整的压缩 HTML 任务如下：

// 压缩 public 目录内 html
gulp.task("minify-html", () => {
    return gulp
        .src("./public/**/*.html")
        .pipe(
            htmlmin({
                removeComments: true, // 清除 HTML 注释
                collapseWhitespace: true, // 压缩 HTML
                collapseBooleanAttributes: true, // 省略布尔属性的值 <input checked="true"/> ==> <input />
                removeEmptyAttributes: true, // 删除所有空格作属性值 <input id="" /> ==> <input />
                removeScriptTypeAttributes: true, // 删除 <script> 的 type="text/javascript"
                removeStyleLinkTypeAttributes: true, // 删除 <style> 和 <link> 的 type="text/css"
                minifyJS: true, // 压缩页面 JS
                minifyCSS: true, // 压缩页面 CSS
                minifyURLs: true,
                ignoreCustomFragments: [
                    /(\s*<span class="math inline">.*?<\/span>\s*)/gi // 匹配并保留 <span class="math inline"> 前后的空格
                ],
            })
        )
        .pipe(gulp.dest("./public"));
});