为 org 文件增加 badge

Question

github 项目中经常都会包含很多 badge，这些 badge 能够很直观地展示出项目的状态来。

然而大多数 badge 生成的站点提供的 badge 代码都是 markdown 格式的，而缺少 org 格式的。 比如下面是 netlify 提供的 badge 代码：

[![Netlify Status](https://api.netlify.com/api/v1/badges/3b4ebb33-1ce2-4238-9a69-e4ecdafd2f1a/deploy-status)](https://app.netlify.com/sites/thirsty-pike-764a9b/deploys)

要在 org 文件中增加 badge 就必须手工将之转成 org link 的格式。

哪些 org link 会被转换成 image

org 并没有像 markdown 一样专门定义了一套语法来指明链接是图片而不是引用。

在 ox.el 的源代码中有这么一段注释：

;; `org-export-inline-image-p' returns a non-nil value when the link
;; provided should be considered as an inline image.

也就是说一个 link 是应该看成引用链接还是图片是由 org-export-inline-image-p 这个函数来决定的

然而具体到 org-html 转换来说，根据 ox-html 中的代码，一个 org link 转换成 image 必须满足两个方面的条件：

1. org-html-inline-images 的值需要设置为非 nil
2. 链接要被 org-export-inline-image-p 函数识别成图片，识别的规则由 org-html-inline-image-rules 决定

相关代码如下:

((and (plist-get info :html-inline-images)
      (org-export-inline-image-p
       link (plist-get info :html-inline-image-rules)))
 (org-html--format-image path attributes-plist info))

(:html-inline-images nil nil org-html-inline-images)

(:html-inline-image-rules nil nil org-html-inline-image-rules)

而 org-html-inline-image-rules 的默认值为:

(defcustom org-html-inline-image-rules
  '(("file" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'")
    ("http" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'")
    ("https" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'"))
  "Rules characterizing image files that can be inlined into HTML.
A rule consists in an association whose key is the type of link
to consider, and value is a regexp that will be matched against
link's path."
  :group 'org-export-html
  :version "24.4"
  :package-version '(Org . "8.0")
  :type '(alist :key-type (string :tag "Type")
                :value-type (regexp :tag "Path")))

也就说以 .jpeg, .jpg, .png, .gif 或 .svg 结尾的链接才会被认为是图片。

在 org 文件中添加 badge

通过分析，我们可以知道，若 badge 给出的链接本身就是以 .jpeg, .jpg, .png, .gif 或 .svg 结尾的，那么很简单，我们只需要将

[![$alt]($image_linke)](link)

转换成

#+ATTR_HTML :alt $alt
[[$link][$image_link]]

就可以了（其中通过 #+ATTR_HTML 来为 image 添加 alt 属性）。

但是对于那些不是以 .jpeg, .jpg, .png, .gif 和 .svg 结尾的链接则似乎只能通过定义 buffer local 的 org-html-inline-image-rules 来实现了。

比如下面这段 org 代码

# -*- org-html-inline-image-rules: (("https" . "deploy-status\\'")); -*-

[[https://app.netlify.com/sites/thirsty-pike-764a9b/deploys][https://api.netlify.com/api/v1/badges/3b4ebb33-1ce2-4238-9a69-e4ecdafd2f1a/deploy-status]]

导出为 HTML 后会变成

<div>
<p><a href="https://app.netlify.com/sites/thirsty-pike-764a9b/deploys"><img src="https://api.netlify.com/api/v1/badges/3b4ebb33-1ce2-4238-9a69-e4ecdafd2f1a/deploy-status" alt="deploy-status" /></a>
</p>
</div>

github 直接渲染

由于 github 不支持 buffer local 变量，其对 org 的渲染也不是很完善，因此对于非 .jpeg, .jpg, .png, .gif 和 .svg 结尾的链接似乎是没有办法显示为图片的。

但是值得指出的是，有些 badge 服务提供的链接是允许在最后面添加后缀的，比如 netlify 提供的 badge，我可以在其图片链接后面增加 .png 也不会影响badge的生成。 因此上面那段 markdonw 代码我可以改写成

[[https://app.netlify.com/sites/thirsty-pike-764a9b/deploys][http://www.wenjiangs.com/wp-content/uploads/2023/01/deploy-status.png]]