3 年前（2023 年），为了尽可能弥补 Obsidian 与 Hexo 之间语法功能适配的隔阂，我探索及开发了 站内文章多款插件，试图缩小两个强大软件的语法隔阂。其中，对于双链功能的语法适配插件 hexo-filter-titlebased-link 最为核心。当时的插件已经可以识别双链的语法结构，并正确链接到文章；后来，自定义链接 HTML 模板功能为链接样式提供更多客制化选项。实质上，这个插件的潜力还没有发挥出来：我们可以读取文章 Front-Matter 中的信息注入到渲染后的双链中；也可以把插件工作时整理的双链信息提取出来，供网站所有者进行数据洞察和数据分析，实现更多有趣的功能。

自 hexo-filter-titlebased-link v0.3.0 版本之后，插件支持 Front-Matter 信息注入；提供双链信息的获取方式，为 Hexo 主题定制提供页面信息，也可以导出全局 JSON 数据。

项目地址：uuanqin/hexo-filter-titlebased-link

本文可以看做是 hexo-filter-titlebased-link 插件的中文（非正规）文档，介绍了插件的基本功能，并通过一些示例介绍这些功能可能的玩法。同时欢迎大家提供插件相关的建议，或展示更多有趣的奇思妙想~

插件的安装与配置

博客项目下打开终端输入并运行以下命令：

1

npm install hexo-filter-titlebased-link --save

然后在 _config.yaml 中加入以下配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

titlebased_link:
  enable: true
  attribute_mapping: {} # e.g., { "category": "cat" }
  custom_html:
    link_attributes: "" # Additional attributes for all <a> tags
    before_tag: ""
    after_tag: ""
    before_text: ""
    after_text: ""
  backlinks:
    enable: false        # Must be `true` to use indexing features
    inject_to_post: false # Access via page.bi_links in themes
    generate_json: ""
    export_local: ""     # Path to save JSON on your local computer

在接下来的章节中，我将会对这些主要的功能进行说明。

基本功能：博客双向链接（Wiki Link）

插件可以识别页面或文章中的形如 [[Title]] [[Title#Anchor]] 或 [[Title|Alias]] 的双向链接（Wiki Links，Internal Links^[1]）语法，并将其渲染为指向实际文章的链接，就如同在 Obsidian 中展现的那样。

例子：

1
2
3
4
5

这是 文章 B, 

你可以点击 [[文章 A]],

或 [[文章 A|Any title]].

经过 Hexo 渲染后，HTML 将会为：

1
2
3

<p>这是 文章 B,  </p>
<p>你可以点击 <a href="/p/mypost1_permalink/">文章 A</a>,</p>
<p>或 <a href="/p/mypost1_permalink/">Any title</a>.</p>

可见，插件就是把双向链接的语法直接「翻译」为指向正确链接的 <a> 标签。

自定义渲染后链接的 HTML 形式

为了能够渲染成更复杂的形式，插件预留有插槽供用户自主定制——通过 custom_html 参数进行配置：

1
2
3
4
5
6
7
8
9

`
${config.custom_html.before_tag}
    <a ${config.custom_html.link_attributes} href="/p/mypost1_permalink/">
        ${config.custom_html.before_text}
        my_post_1
        ${config.custom_html.after_text}
    </a>
${config.custom_html.after_tag}
`

例如：

1
2
3
4
5
6
7
8

titlebased_link:  
  enable: true   # enable this plugin  
  custom_html:  
    link_attributes: 'class="uuanqin-bilink" target="_blank"'  
    before_tag: ''  
    after_tag: ''  
    before_text: '<span class="bilink-pop-up">弹窗</span>'  
    after_text: ''

得到的链接是这样的：

1
2
3
4

<span class="bilink-pop-up">弹窗</span>
<a class="uuanqin-bilink" target="_blank" href="/p/mypost1_permalink/">
	my_post_1
</a>

关于这个「气泡链接」的小项目，详见 站内文章这篇文章。虽然文章中介绍的是另一个插件，但是自定义插槽的功能是一样的。

通过插槽的方式，我们可以实现链接前后 HTML 块的添加、<a> 属性的添加（如添加 class 属性以调整样式）。但如果我们要求根据文章的特征进行不同形式双链的渲染，那么可以考虑后面的 attribute_mapping 选项进行实现。

将文章 Front Matter 字段内容映射到链接中

通过配置 attribute_mapping，我们可以将文章的 Front-Matter 信息，以 data-xxx 的形式注入到链接中。示例配置如下：

1
2
3
4

titlebased_link:
  enable: true
  attribute_mapping: 
    "access.enable": auth # 表示将 Front Matter 中 access.enable 字段注入到 <a> 标签的 data-auth 属性中。

利用这一点我们可以生成不同样式的链接。比如：

更进阶地，我们可以将链接指向的文章封面和描述嵌入到相关属性中，并实现小窗预览效果：

通过多种形式获取/导出关系图谱信息

我认为导出图谱信息这个功能是插件最有用的地方。有了文章的双链信息，我们可以把握住网站文章之间的基本拓扑结构。更自然的，我们会想到实现文章关系拓扑图的绘制。

为博客主题提供文章的双向链接信息

当插件进行以下配置时，我们可以在博客构建时将双链信息存储在内存供主题使用：

1
2
3
4
5

titlebased_link:  
  enable: true   # enable this plugin    
  backlinks:  
    enable: true        # Must be `true` to use indexing features
    inject_to_post: true # Access via page.bi_links in themes

例如，在 Hexo-Butterfly 主题源代码中，我们可以通过 page.bi_links 可获取当前文章的出链入链信息。其信息结构示例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

inbounds:
  # Pages that link TO this post (Backlinks/Mentions)
  - id: "project-2026-overview" 
    title: "Project Overview 2026"
    path: "p/2026/04/01/overview/"
  - id: "index-garden"
    title: "Digital Garden Index"
    path: "p/2026/01/15/index/"

outbounds:
  # Pages that this post links TO (References)
  - id: "hexo-plugin-guide"
    title: "Hexo Plugin Guide"
    path: "p/2024/04/12/plugin-dev/"

这里通过一个小小例子，展示如何将双链信息融入页面中。

在主题源代码目录下 \themes\butterfly\layout\includes\header\post-info.pug 相应位置增加以下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// 双链信息页  
if page.bi_links  
  if page.bi_links.inbounds.length + page.bi_links.outbounds.length > 0  
    .meta-thirdline  
      span.post-meta-separator |  
      span.post-meta-outbounds  
        i.fa-solid.fa-right-from-bracket.fa-fw.post-meta-icon  
        span.post-meta-label= '出链:'  
        span= page.bi_links.outbounds.length  
      span.post-meta-separator |  
      span.post-meta-inbounds  
        i.fa-solid.fa-right-to-bracket.fa-fw.post-meta-icon  
        span.post-meta-label= '入链:'  
        span= page.bi_links.inbounds.length

然后根据需要，微调 \themes\butterfly\source\css\_layout\head.styl 的样式即可。

将双链信息以 JSON 的形式导出（博客输出目录/本地位置）

我们可以将这个双链信息以 JSON 的形式进行导出，可以导出到 Hexo 生成的 public 目录，或本地电脑中的其他位置。

当我们进行如下配置时：

1
2
3
4
5
6

titlebased_link:  
  enable: true   # enable this plugin  
  backlinks:  
    enable: true        # Must be `true` to use indexing features  
    generate_json: "api/backlinks.json"
    export_local: "D:\abc\Desktop\link.json"

JSON 文件将会输出到：

• Hexo 的 public 目录下的 api/backlinks.json 中，博客发布时我们可以通过 https://your-domain.com/api/backlinks.json 进行访问。
• 本地电脑的 D:\abc\Desktop\link.json 文件中。

JSON 格式示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

{
	"dht11 驱动程序": {  
	  "id": "dht11 驱动程序",  
	  "path": "p/c497cb3f/",  
	  "isDraft": false,  
	  "title": "DHT11 驱动程序",  
	  "attrs": {  
	    "data-category": "嵌入式" 
	  },  
	  "bi_links": {  
	    "inbounds": [  
	      {  
	        "id": "实现阿里云温湿度监控及 led 点灯",  
	        "title": "实现阿里云温湿度监控及 LED 点灯",  
	        "path": "p/de31d8e3/"  
	      }  
	    ],  
	    "outbounds": [  
	      {  
	        "id": "stm32 延时函数（freertos）",  
	        "title": "STM32 延时函数（FreeRTOS）",  
	        "path": "p/c5d0cc56/"  
	      }  
	    ]  
	  }  
	}
}

有了双链信息，我们可以轻松的使用各种可视化库绘制博客文章的关系图，比如本站的 站内文章关系图谱：

或者在主题侧边栏中提供当前文章的关系视图：

后记

文章推荐

更多 Obsidian 语法在 Hexo 中的适配详见 站内文章这篇文章；Hexo+Obsidian 工作流协同请看 站内文章这篇文章。

碎碎念

导出双链信息真的只是顺手的事情，想象中的 Obsidian Like 博客其实也没有那么难…

本文参考

• uuanqin/hexo-filter-titlebased-link: Transfer wiki links (based on the title) in Markdown files to permalink. 将基于标题的双向链接转换为 Hexo 设定的永久链接。