Hexo 博客适配 Obsidian 新语法
为了写这篇文章我手撸两个插件😭。还请各位小星星⭐支持一下~~
OFM
Obsidian 除了支持大部分 CommonMark 语法、部分 GFM 功能以及 LaTeX 外,Obsidian 增加了一些新语法 [1]。
Syntax | Description |
---|---|
[[ ]] | Internal links |
![[ ]] | Embedding files |
![ name | 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。然后配置上去即可(后面有教程):
Internal links 双向链接渲染解决方案
只需安装一个插件(我本人写的哦!)就可以解决:
1 | npm install hexo-filter-titlebased-link --save |
使用插件前确保所有标题都是独一无二的。
喜欢的话赏个⭐~
旧方案仍然可以工作,不过操作繁琐。详见:Obsidian Internal links 双向链接渲染解决方案
Callouts 标注块
找了半天终于找到这个宝藏插件,这里默默感谢作者 widcardw。现在 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 | # markdown_it_plus 语法渲染插件选项 |
打开 mdit-plugin-callouts
插件安装位置,复制出两个 css 文件:
粘贴到你平时放外部 css 的地方,并重命名以免影响到其它 css 文件,比如下图:
- index.css 重命名为 callout_blocks.css
- common.css 重命名为 callout_blocks_common.css
打开 callout_blocks.css,把开头的 common.css
改为对应重命名后的 callout_blocks_common.css
。
接下来根据你使用的主题的说明,引入外部 CSS 文件 callout_blocks.css
。Butterfly 主题的做法为在主题配置文件 _config.butterfly.yml
中插入:
1 | inject: |
现在你可以测试一下 Hexo 渲染后的页面正不正常了。但其实 Butterfly 中 Callouts 的 Note 块中 padding-left 属性不太正常,这是 Butterfly 中 CSS 覆盖导致的:
解决办法是,把 callout_blocks_common.css
中所有的 note
替换为 notice
或你想要的字符,这样会导致在两种应用的显示情况:
- Hexo 中成功渲染原
note
的 Callouts 块,但以后使用该块的语法为:
1 | > [!notice] |
- Obsidian 中不受影响,因为任何未指定字符都渲染成原来 Note 块的样子。(得亏只有这个块有问题…)
External images 图片大小
Obsidian 对于图片大小尺寸调整有其自己的一套 语法:
1 | ![img|100x145](path/to/img) // 宽100px,高145px |
通过搜寻并没有很好的方案解决,于是我就自己手撸一个了…
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 双向链接插件(我直接写了一个新插件)
本文参考
- 【Hexo】选择更高级的 Markdown 渲染器_hexo markdown_Xavier Jiezou 的博客
- hexo 更换 markdown 渲染器 @upupming/hexo-renderer-markdown-it-plus_markdown-it-katex_Ann’s Blog 的博客-CSDN 博客
- Hexo 多种 Markdown 渲染器对比分析 | 竹山一叶 (zsyyblog.com)
- mdit-plugin-callouts - npm (npmjs.com)
- Notes on Markdown-it and Building a Plugin | Joshua’s Docs (joshuatz.com)
- 记一次markdown-it插件学习 - 掘金 (juejin.cn)
- markdown-it 13.0.2 API documentation | MarkdownIt (class)
- markdown-it demo
- javascript - 编写markdown-it的插件和规则 - FE_Framework_and_Engineering - SegmentFault 思否
- Markdown-It 的解析过程 - 简书 (jianshu.com)
- 为markdown-it编写插件 - 简书 (jianshu.com)
- markdown-it 原理解析 · Issue #252 · mqyqingfeng/Blog (github.com)
- markdown-it 源码分析及插件编写:parse 和 token(1/3) - 知乎 (zhihu.com)
- tcatche/hexo-filter-link-post: Transfer relative post link in markdown file to post link. 将文件里的通过相对路径引用的 markdown 文件转为对应的文章的链接 (github.com)
- 永久链接(Permalinks) | Hexo
- 插件 | Hexo
- moelody/hexo-link-obsidian (github.com)
- 渲染 | Hexo
- decodeURI() - JavaScript | MDN (mozilla.org)
- 正则表达式可视化工具 | 菜鸟工具 (jyshare.com)
- hexo 教程之为 hexo 编写一个插件_编写hexo插件-CSDN博客
- JavaScript 之 replace() 方法的第二个参数为匿名函数时的理解(涉及正则)_js replace 匿名函数 csdn-CSDN博客
- 深入理解str.replace方法-CSDN博客
Markdown 相关语法规范详见 Markdown 渲染测试 ↩︎