Markdown博客站内引用问题

2022-12-13 ⏳4.8分钟(1.9千字) g

使用 Markdown 写博客绕不过引用链接的问题。源文件扩展名是.md,但转换后会变成.html。为了正常跳转,写站内引用链接时只能使用 HTML 文件对应的路径。但这样一来,在编辑的时候就没法跳转到对应的.md文件了。最近抽空给 pandoc 写了个 lua-filter,算是比较完美地解决了这个问题。今天分享给大家。

举个例子说明一下。比如我们有如下目录结构:

demo
├── bar
│   └── baz.md
└── foo.md

我们想在baz.md文件中引用foo.md文件。如果不做任何处理,我们需要在baz.md写[foo](../foo.html)。因为foo.md最终会转换成foo.html,如果写成[foo](../foo.md)读者就无法正常打开foo.html文件。但如果照顾了读者,写成[foo](../foo.html),我们在编辑bar.md的时候就没法切换到foo.md文件,因为扩展名不匹配。

我还用 hugo 框架,它会把 Markdown 转换成文件夹。比如foo.md最终会变成foo/index.html。这样做的好处是不需要在引用的时候指定扩展名,可以直接写成[foo](../foo/)。但依然无法在编辑器内切换到对应的foo.md文件。

问题的关键是不论链接写成[foo](../foo.html)还是[foo](../foo/),都是对应转换后的 HTML 文件,并没有 Markdown 源文件与之对应。解决这个问题的终极方案是在 Markdown 文件中直接引用.md文件路径,然后在生成 HTML 文件的时候再将其转换成.html文件对应的路径。

本站使用 pandoc 构建,而 pandoc 支持使用 lua-filter 扩展 Markdown 转 HTML 的功能。今天我们就使用 lua-filter 将.md链接转换成对应的.html链接。

最简单的 lua-filter 如下,需要返回一个 table,每个元素都是 pandoc 对象。pandoc 对象的 key 对应 Markdown 的语法单元。比如我们希望处理所有链接,所以需要给Link设置回调函数。

return {{
  Link = function (link)
    -- do something
    return link
  end
}}

讲道理 lua-filter 还是比较复杂的,本文只用到一点皮毛。有志深入研究的读者可以仔细阅读官方文档。

Link对象最重要的属性是target,里面保存的就是链接的目标地址。Markdown 中的[foo](../foo.md) 对应的target属性就是../foo.md。Link的其他属性请参考官方文档。

接下来的问题就是怎么在 lua 中将.md转换成.html。这里不能无脑把所有的.md都转成.html,我们有可能真得会引用外站的 Markdown 文件。我想到的处理方案是只看站内引用,也就是检查链接是否以http开头。只对站内链接做转换。但这种办法也有问题,就是无法引用站内 Markdown 文件了。考虑到我的平台会把所有站内.md转换成.html文件,而且不允许直接访问 Markdown 源文件,所以问题不大😜

lua 的语法比较古怪,跟 C 家族语言差距比较大。

lua 注释以--开头。

lua 中不相等用~=表示,而不是常见的!=。

字符串截取子串使用sub函数,第一个参数表示开始位置,第二个表示子串长度。lua 还有一个特殊的地方是下标从1而非0开始。

此外,sub函数还支持传入一个参数。sub(3)表示跳过前两个字符,sub(-3)表示从结尾提取长度为3的子串。而更复杂的sub(1,-3)则表示提取从开始到倒数第3个位置为止的子串,也就是剔除最后3-1个字符的子串。

我们需要的 lua 代码如下:

-- 检查链接开头不是 http
-- 而且结尾必须是 .md
if t:sub(1,4) ~= "http" and t:sub(-3) == ".md" then
  -- 剔除最后的 md 再附加 .html
  link.target = t:sub(1,-3).."html"
end
return link

在转换的时候需要使用--lua-filter参数指定 lua 文件路径:

pandoc --lua-filter $LUA_FILTER bar.md -o bar.html

问题到这里基本就解决了。我们在写 Markdown 文件时可以直接根据相对路径填写对应的.md文件路径。pandoc 在转 HTML 文件时会自动将.md转换成.html,同时解决了读者和作者的跳转问题。

注意,如果你的 pandoc 不是最新版本,则可能会碰到超链接<a>变成<embed>的问题,具体可以参考这个issue。解决方案是安装最新版本的 pandoc。

但是相对路径虽然方便,维护上也很容易,却不利于 SEO。说白了就是别人转载了你文章,里面的相对链接就失效了。为了尽可能多地增加外链,最好还是把所有相对路径改为绝对路径。最好把站内路径全都转换成完整的URL。但这么一来不但会引入大量的维护成本,还会再一次导致无法在编辑器内跳转的问题。

既然可以用 lua-filter 修改连接的后缀,那就一定可以将相对链接改为 URL。让我们一鼓作气,完整地解决这个问题。

这里有两个核心问题。第一个是在 lua 脚本中获取当前 Markdown 文件的路径。第二个是根据当前路径和相对路径计算完整 URL。

第一个问题查了半天,它隐藏在PANDOC_STATE这个全局变量的input_files属性里。这是一个数组,文档没细讲它的构成。但实验发现数组的第一个元素就是 Markdown 文件的路径。所以文件路径如下:

local p = PANDOC_STATE.input_files[1]

第二个问题需要自己实现路径替换函数,因为 lua 标准库没有路径计算相关的函数😂

算法也比较简单。假设当前路径为a=/a/b/c/d.md,相对路径为b=../../../1.md,我们希望得到/1.md。对a来说,/d.md不参与计算,应该事先跳过。然后遍历b,每碰到一个../就将其剔除同时还要把a对应的路径也向上移动一级。整个过程如下:

            b a
../../../1.md "/a/b/c"
   ../../1.md "/a/b"
      ../1.md "/a"
         1.md ""

但还有一些特殊情况需要处理,比如应该剔除b中的./前缀等。

逻辑上没有问题了,编码时还会遇到另一个拦路虎find函数。lua 中查看子串使用find函数,但这个函数只能从左向右查。而我们处理当前路径的时候是从右向左查的。我搜了一下,发现大家是先把字符串反过来,然后从左往右处理,最后再反转回去😂完整代码如下:

-- realpath convert path with .. to absolute path
--
-- "/1.md" == realpath("a.md", "1.md")
-- "/1.md" == realpath("/a.md", "1.md")
-- "/1.md" == realpath("/a.md", "./1.md")
-- "/1.md" == realpath("/a/b.md", "../1.md")
-- "/1.md" == realpath("/a/b/c.md", "../../1.md")
-- "/1.md" == realpath("/a/b/c/d.md", "../../../1.md")
function realpath(a, b)
  if a:sub(1,1) ~= '/' then a = '/' .. a end
  c = a:reverse()
  _,j = c:find("/")
  c = c:sub(j+1,-1)
  if b:sub(1,2) == "./" then
    b = b:sub(3)
  end
  while (true) do
    _,i = b:find("../")
    _,j = c:find("/")
    if i == nil or j == nil then break end
    b = b:sub(i,-1)
    c = c:sub(j+1,-1)
  end
  if b:sub(1,1) ~= '/' then b = '/' .. b end
  return c:reverse()..b
end

上面的 lua-filter 修改链接的部分需要改成:

-- 提取环境变量
local envs = pandoc.system.environment()
local url = envs["site_url"]
local p = PANDOC_STATE.input_files[1]
-- 计算完整路径
t = realpath(p, t)
-- 拼接完整URL
t = url .. t
link.target = t:sub(1,-3).."html"

到这里才算完整解决了 Markdown 博客系统的引用链接问题。希望能对大家有启发。