为了写这篇文章我手撸两个插件😭。还请各位小星星⭐支持一下~~

OFM

Obsidian 除了支持大部分 CommonMark 语法、部分 GFM 功能以及 LaTeX 外，Obsidian 增加了一些新语法 [1]。

Syntax Description
[[ ]] Internal links
![[ ]] Embedding files
![ | width x height ]() External images with dimensions
%% Comments
> [!note] Callouts
注意

Obsidian 不支持在 HTML 块中使用 Markdown 语法或空行。

为了使得这些 Obsidian 语法在 Hexo 中产生作用，我们可以安装插件改进这一点，从而得到更丰富的书写体验。

温馨提示

使用增强的 Markdown 语法会增加你对特定软件和插件的依赖性，但能提升你的写作体验。在进行相关配置时请酌情考虑。

介绍解决方案前先简要说明一下我对 Markdown 渲染相关的插件的理解。

Hexo 里的 Markdown 渲染引擎

有了 Markdown 渲染引擎，Hexo 才能将 Markdown 格式的内容渲染成 HTML 网页。不同的渲染器支持的语法不同。这里列出以下三种渲染引擎。

渲染引擎 功能
hexo-renderer-marked Hexo 预装渲染引擎。不支持复杂的数学公式
hexo-renderer-markdown-it 取代第一个的渲染器，渲染更快，更符合 CommonMark 规则
hexo-renderer-markdown-it-plus 上一个渲染器的分支，可能更好用了吧

上面的渲染引擎中内置不同的插件。我使用的 hexo-renderer-markdown-it-plus 支持扩展，我们可以在 npm 插件市场选择一款插件用以扩展更多语法（一般名为 markdown-it-xxxx）。

比如我安装的支持任务列表语法（GFM[2]）的插件 markdown-it-task-lists，以及后文讲到的 Callouts 语法（OFM）插件 mdit-plugin-callouts。然后配置上去即可（后面有教程）：

image.png

旧方案见：Obsidian Internal links 双向链接渲染解决方案

只需安装一个插件（我本人写的哦！）就可以解决：

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

使用插件前确保所有标题都是独一无二的。

Readme Card

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

喜欢的话赏个⭐~

Callouts 标注块

找了半天终于找到这个宝藏插件，这里默默感谢作者 widcardw

对于这种需要另外渲染的新语法，我使用一款 npm 插件：mdit-plugin-callouts - npm (npmjs.com)，来增强渲染这一部分的内容。

这款插件本身是用于使 vite 博客网站支持 Obsidian 的 Callouts 用的，但稍微调整下也可以运用于 Hexo。

首先打开项目文件夹安装插件：

1
npm install mdit-plugin-callouts

Hexo 博客中我安装的渲染器是 hexo-renderer-markdown-it-plus，它可以通过配置文件拓展其他 Markdown 渲染插件。

在 _config.yml 中增加相应配置以添加插件：

1
2
3
4
5
6
7
8
9
# markdown_it_plus 语法渲染插件选项
markdown_it_plus:
    plugins:
        # Obsidian Callouts
        - plugin:
            name: mdit-plugin-callouts
            enable: true
            options:
                # this is plugin option

打开 mdit-plugin-callouts 插件安装位置，复制出两个 css 文件：

image.png

粘贴到你平时放外部 css 的地方，并重命名以免影响到其它 css 文件，比如下图：

  • index.css 重命名为 callout_blocks.css
  • common.css 重命名为 callout_blocks_common.css

image.png

打开 callout_blocks.css，把开头的 common.css 改为对应重命名后的 callout_blocks_common.css。

image.png

接下来根据你使用的主题的说明，引入外部 CSS 文件 callout_blocks.css。Butterfly 主题的做法为在主题配置文件 _config.butterfly.yml 中插入：

1
2
3
4
inject:
  head:
    # callout blocks
    - <link rel="stylesheet" href="/css/callout_blocks.css">

现在你可以测试一下 Hexo 渲染后的页面正不正常了。但其实 Butterfly 中 Callouts 的 Note 块中 padding-left 属性不太正常，这是 Butterfly 中 CSS 覆盖导致的：

image.png

image.png

解决办法是，把 callout_blocks_common.css 中所有的 note 替换为 notice 或你想要的字符，这样会导致在两种应用的显示情况：

  • Hexo 中成功渲染原 note 的 Callouts 块，但以后使用该块的语法为：
1
2
> [!notice]
> contents
  • Obsidian 中不受影响，因为任何未指定字符都渲染成原来 Note 块的样子。（得亏只有这个块有问题…）

External images 图片大小

Obsidian 对于图片大小尺寸调整有其自己的一套 语法：

1
2
![img|100x145](path/to/img) // 宽100px，高145px
![img|100](path/to/img)     // 宽100px

通过搜寻并没有很好的方案解决，于是我就自己手撸一个了…

Readme Card

Git 仓库地址：uuanqin/markdown-it-obsidian-imgsize: Obsidian图片大小处理插件 (github.com)

喜欢的话赏个⭐~

使用方法很简单，仿照上一小节 Callouts 的解决方法，安装这个 markdown-it-plugin 即可：

1
npm i markdown-it-obsidian-imgsize --save

这一层打通以后，你就可以放心使用 Obsidian 中方便调整图像大小的插件啦，比如我正在用的这个：nicojeske/mousewheel-image-zoom (github.com) 鼠标滚轮调整图片大小。

后记

心路历程

我的第一次，全给弄在这东西上了呢🥵

解决 Callouts 问题的过程中，搜到 widcardw 的博客并产生启发，于是我的第一款 NPM 插件 markdown-it-obsidian-imgsize 诞生了。开发杂记详见：第一次开发 npm 插件。

关于双链渲染，心路历程详见：第一次写 Hexo 插件

后续考虑改进

  • 写一个 markdown-it 插件 适配 Obsidian 图片大小的语法（我真的写了一个新插件）
  • 重写 callsout 插件适配 Hexo
  • 重写 Hexo-Obsidian 双向链接插件（我直接写了一个新插件）

本文参考

  1. Obsidian Flavored Markdown - Obsidian Help ↩︎

  2. Markdown 相关语法规范详见 Markdown 渲染测试 ↩︎