🪴 8Cats & Me

0%

🎯 置顶

博客发布流程

🌱
🌴
⌛️ 8min, 1455words
🗓 History

基于quartz ↗和ccm-publisher ↗插件，发布obsidian笔记到github pages

  • 使用submodule，使得编译和发布博客内容完全分离，更加自由和方便

Tip

  1. 本文使用quartz_demo作为quartz的编译库
  2. 实际应用中你的仓库名称应该是yourname.github.io, 这里为了说明流程，就用quartz_demo了
  3. 使用content_demo作为笔记库， content_demo作为说明使用

TLDR

  1. 准备Quartz环境，参考 Quartz: Get Started ↗, 作为编译库
    • 注意在quartz.config.ts配置文件中修改baseUrl为yourname.github.io
  2. 准备一个空的仓库，用于上传你的笔记（笔记库）
    • 至少需要在根路径下有1个index.md文件
  3. 复制github-action配置文件
    1. 复制并配置这个action配置文件 ↗到编译库
    2. 复制并配置这个action配置文件 ↗到笔记库
  4. 尝试push笔记到笔记库，查看两个库的action是否成功
  5. 所有action执行成功后,转到yourname.github.io查看效果

操作步骤

准备环境

  1. 准备Quartz环境，参考 Quartz: Get Started ↗
  2. 初始化自己的Quartz编译库，这里应该是叫yourname.github.io, 替换yourname为你自己的github账号名称 
    $ git remote -v
# quartz_demo 替换成你自己的 yourname.github.io
origin	[email protected]:CatCodeMe/quartz_demo.git (fetch)
origin	[email protected]:CatCodeMe/quartz_demo.git (push)
upstream	https://github.com/jackyzha0/quartz.git (fetch)
upstream	https://github.com/jackyzha0/quartz.git (push)
  3. 跟之前的步骤一样，在github初始化另一个空的仓库, 用于上传你的obsidian笔记，假如叫content_demo2
    • 这里只需要初始化,不需要其他操作，像这样
      20240322-publish_init_content.png

配置submodule

  1. 到这一步开始, 跟官方使用的单库发布方式区别开来, 我们使用submodule
  2. 配置submodule
$ cd quartz_repo
$ git rm -r --cached content
# 替换CatCodeMe/content_demo.git为你自己的仓库路径
$ git submodule add [email protected]:CatCodeMe/content_demo.git content
$ git commit -m "add submodule"
$ git push
  1. 到这一步, quartz_demo仓库和content_demo仓库就使用submodule建立了联系; 蓝色链接可能不一样，是正常现象；如果点击content文件夹能够调整到content_demo仓库就证明配置成功了
    20240324-publish_add_submodule.png

配置Github action实现自动编译

对于新手可以参考后续的步骤, 熟悉操作的话可以直接参考并调整这个action配置 ↗

配置笔记库(content_demo)

可以直接在github, 如果喜欢git客户端工具也可以clone到本地再操作。

新建一个文件（点击上图的create a new file蓝色链接即可）, 叫.github/workflows/deploy.yml

  • 文件夹路径必须是 .github/workflows , 文件后缀必须是.yml, 文件名没有要求，只要符合github要求即可
  • deploy.yml 的文件内容，可以参考这里 deploy.yml ↗ ；复制并修改好内容后，点击右上角的commit 按钮，即可保存当前文件
    20240322-publish_zh_yml.png
    • repo 选项替换成步骤2中名称，结构是yourname/yourname.github.io
    • token 选项是github的鉴权token，使用时要注意
      1. ${{ secrets.gh_action_token_PAT}} 这个设置里，gh_action_token_PAT 是自定义的token名称，可以自行决定，最好不要是中文，空格。
      2. 在这里 ↗生成token （最好是在浏览器的新标签页打开，会方便很多）
        20240323-publish_start_generate_token.png
      3. 选择该token可以使用的仓库
        20240322-publish_select_repo.png
      4. 设置token权限，当前页面下滑即可; 展开 Repository permissions ，找到 Actions 和 Contents 两个选项，Access 都设置为 Read and write
      5. 点击 generate token，（❗️先复制并保存这个生成的token到其他地方，后续需要使用. 如果忘记了，可以重新执行上边的3步，再生成一个新token即可）
      6. 复制好之后可以刷新或者再次点击左侧导航栏进入Fine grained tokens 页面，选择并点击刚才的生成token，可以看到类似下图的效果
        20240324-publish_token_settings.png
      7. 回到刚才生成的仓库content_demo首页, 点击 settings 选项卡，进入设置页面，为当前仓库添加刚才生成的token授权, 点击New repository secret按钮
        20240322-publish_add_token_repo.png
      8. 接下来添加token, 需要注意
        1. Name 必须和action配置文件中的gh_action_token_PAT 这个名称保持一致, 当然你要是使用的其他名称，那么修改.github/workflows/deploy.yml 的配置和这里的Name一样就可以了
        2. Secret就是刚才复制并保存的token
        3. 设置好后点击Add secret 保存即可
          20240322-publish_add_token_repo_2.png
      9. 到这里，当前仓库的action就配置好了。此时，这个仓库应该是这样的结构
        20240322-publish_content_repo_demo.png

配置quartz编译仓库

  1. 回到quartz_demo仓库，直接修改clone原始仓库后(quartz)的ci.yaml文件内容
    1. 和笔记库一样，这个文件也必须在.github/workflows/文件夹下，名称无所谓
    2. 可以直接覆盖ci.yaml的内容, 也可以删除后新建一个yaml配置文件
  2. 我们这里选择修改
    • 修改后的内容, 使用我的配置文件 ↗内容即可，只有1点需要注意, token名称gh_action_token_PAT需要和你的仓库配置保持一致
      20240324-pulish_quartz_action_token.png

配置结束

  • 至此所有配置完成, 尝试发布笔记到content_demo仓库，并检查action（默认情况下会自动发通知到github邮箱）是否执行成功。
  • 之后检查你的https://yourname.github.io 目标网页即可

优缺点

优点

  • 使用submodule的模式, 可以做到笔记和编译工具完全分离, 即使之后迁移到其他工具，理论上也没有什么影响
  • 配置完成所有流程自动化, 你需要做的就只有写笔记，发布到笔记仓库，等待生效即可
    • 发布笔记可以使用obsidian的插件，这里推荐我自己开发的ccm-publisher ↗插件

缺点

  • 不支持本地查看效果，这个可以用obsidian插件解决
    • ccm-publisher插件正在开发这个功能，敬请期待

Footnotes

  1. quartz_demo repo ↗ ↩

  2. content_demo repo ↗ ↩

🕸️ 关系图谱