Obsidian 结合 MkDocs¶

背景¶

之前的个人博客搭建方案还是过于繁琐, 不方便发布。步骤一多人就懒

前段时间翻了翻 2024 Gems of the year winners - Obsidian，发现这款插件，配置好后只需在 Obsidian 中添加一个属性，然后点击即可发布。使用无负担，数据不丢失

话不多说，这就来看看部署流程

配置 GitHub 仓库¶

1. 在 Mkdocs 的指导下，使用提供的mkdocs模板 创建自己的仓库
2. 然后按照这个仓库的说明添加 GH_TOKEN 并进行后续操作。这里我用的是细粒度权限 token
3. 然后填写信息运行 Generate website
   • 不出意外应该会失败，出现此错误👉 The URL isn't valid。不过不用担心，不用管
4. 配置 Pages

下面配置可选

域名¶

如果有自己域名，并在 GitHub Pages 中填写了，那记得在 docs 目录下添加 CNAME，不然部署时会将仓库里设置的 Custom domain 清空。

添加后 MkDocs 执行部署时会将此文件添加到根目录

字体¶

1. 将 mkdocs.yml 中的 font 注释掉
2. 使用霞鹜文楷屏幕阅读版 网络字体仓库 ，在 mkdocs.yml 中新增
   

   extra_css:
       - https://cdn.jsdelivr.net/npm/lxgw-wenkai-screen-web/lxgwwenkaiscreen/result.css
       - _static/css/font.css
   

3. 在 _static/css 目录下新建 font.css，并填写
   

   body {
       font-family: "LXGW WenKai Screen",sans-serif;
       font-weight: normal;
   }
   

评论¶

按照文档操作👉 Adding a comment system - Material for MkDocs

注释掉 overrides\partials\comments.html 中的 if page.meta.comments&endif 即可为所有文章开启评论，从而无需在文章中添加 comments 属性

字数统计及阅读时间插件¶

按照文档在 mkdocs.yml 中添加插件

Obsidian-enveloppe 插件使用 uv 管理依赖配置，把前面创建的仓库克隆下来，执行命令更新下配置文件：

pip install uv
uv add mkdocs-statistics-plugin

本地化¶

有些比较隐蔽的提一下：

• overrides\partials\source-file.html 中将作者 Auteur 修改为 Author
• mkdocs.yml 中修改 git-revision-date-localized 的 locale 为 zh

其他¶

详细阅读官方文档 ，按需修改 mkdocs.yml 进行个性化设置

Obsidian 安装插件¶

前面的操作完成后，在 Obsidian 中安装插件。然后按照 Github Configuration 进行配置

1. token 可以和前面生成的共用一个
2. 目录设置，个人使用的是属性 Property key ，对应 categories。另外目录确保以 docs 开头，不然 MkDocs 不会生成对应文章。同理，后面的图片目录也要以 docs 开头
3. 开启 File Menu，这样可以在编辑模式下可右键上传，也可在文件菜单中选择上传。
   • 对应 Upload single current active note 命令，只会上传当前文件及其链接的分享文件（即符合 share: true 的文件）

下面配置可选

修改 PR 标题¶

修改 PR 标题，打开此插件目录，这里是 obsidian-mkdocs-publisher，在 main.js 中搜索 app.vault.getName。

删除 ${this.app.vault.getName().replaceAll(" ","-").replaceAll(".","-")}- 即可将 PR 标题中的 Obsidian 仓库名去掉，只保留日期

中文目录链接¶

对于中文标题必须进行修改后才能正确跳转链接

• mkdocs.yml 中添加 slugify，指定处理逻辑
  

  markdown_extensions:
  - toc:
      permalink: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}
  

• Obsidian 中将 Sluglify anchor in markdown links 设置为 Convert all to …… (strict 模式)

不过由于 obsidian-enveloppe 使用的 slugify 包与 pymdown 不同，细节上还是有差别，比如 / 的处理，导致不是完美匹配

Enveloppe 需要移除特殊字符

成果¶

• GitHub - chu-shen/obsidian-mkdocs

已知不足¶

• 双链、悬浮预览，具体可以对比 obsidian-digital-garden示例站点
  • 悬浮预览使用的是 Tippy.js。效果不好，不能点击，而且必须是完整链接才能预览，所以基本没用
• 部分样式/插件不支持

小 tips¶

• categories 如果添加多个，会在目录中形成嵌套关系。如果使用 / 也会形成嵌套