发布
[[ jekyll ]] 方案
无意间看到的教程obsidian 目前最完美的免费发布方案 - 渐进式教程 — 🌱 oldwinterの数字花园
部署过程中几乎没坑，就算是小白也能大概跑通，需要配置 Ruby 环境
[[ Hugo ]] 方案
[!INFO] 2023-08-30 该方案已废弃
quartz 升级到 V4 后弃用了用Hugo，因为有这两个缺点：
- golang生态，上手门槛高
- 社区活跃度低
现在转用了node.js的生态，作者自己实现了静态生成器和一套插件系统，具体可以去官网看
于是就多了 [[ #quartz 方案 ]]
坑比较多，但是部署后效果比 [[ #jekyll 方案 ]]好上不少，例如深色模式、全局检索
安装
fork 一份jackyzha0/quartz，使用 git clone 拉到本地，进入该项目的目录
删除整个 content 文件夹，将Obsidian工作区关联到 content 文件夹，根据同步方案方式有所不同：
-
[[ Git ]]同步：将工作区仓库添加为子模块
git submodule add 仓库地址 content - 其它方案：直接将整个工作区的内容复制到
content文件夹中即可
预览
如果需要本地预览部署后的效果，首先需要 [[ Golang ]]版本 >= 1.16，其次需要安装Hugo和 hugo-obsidian
在项目根目录中执行 go install github.com/jackyzha0/hugo-obsidian@latest 即可完成 hugo-obsidian 的安装
最后在项目根目录中执行 make serve 来启动开发服务，默认端口为 1313，具体看命令行输出
[!INFO] make 命令
在 [[ Windows ]]下需要安装 mingw来支持
make命令
配置
绝大部分配置都在 data/config.yaml 中修改，该文件中的内容照猫画虎将作者的信息替换成自己的即可
name: NoraH1to # 作者名称
enableToc: true
openToc: false
enableLinkPreview: true
enableLatex: true
enableCodeBlockTitle: true
enableCodeBlockCopy: true
enableCallouts: true
enableSPA: true
enableFooter: true
enableContextualBacklinks: true
enableRecentNotes: true # 是否在主页展示最近更新的文章
enableGitHubEdit: false
enableMermaid: true
GitHubLink: https://github.com/NoraH1to/digital-garden-quartz/tree/hugo/content # 仓库地址
search:
enableSemanticSearch: false
operandApiKey: "REPLACE-WITH-YOUR-OPERAND-API-KEY"
operandIndexId: "REPLACE-WITH-YOUR-OPERAND-INDEX-ID"
description:
我的第二大脑，由 obsidian 驱动。 # 站点描述
page_title: "🧠 缸中大脑" # 主页标题
links: # 页脚的一些跳转链接
- link_name: GitHub
link: https://github.com/NoraH1to
比较重要的配置在 config.toml 中
baseURL = "https://garden.norah1to.com/" # 部署基础路径，必须填对
languageCode = "zh-cn" # 没有作用
defaultContentLanguage = "zh-cn" # 默认语言是英文，这行配置作者没给，查了 hugo 文档自己添加上的
relativeURLs = false
disablePathToLower = true
ignoreFiles = [] # 忽略的文件，需要根据 obsidian 实际情况来修改，我留空
summaryLength = 20
paginate = 10
enableGitInfo = true
[markup]
[markup.tableOfContents]
endLevel = 3
ordered = true
startLevel = 2
[markup.highlight]
noClasses = false
anchorLineNos = false
codeFences = true
guessSyntax = true
hl_Lines = ""
lineAnchors = ""
lineNoStart = 1
lineNos = true
lineNumbersInTable = true
style = "dracula"
[frontmatter]
lastmod = ["date modified", "lastmod", ":git", "date", "publishDate"] # 决定用 format yaml 中的哪个字段来展示最后修改时间
publishDate = ["date created", "publishDate", "date"] # 同上，不过是发布（创建）日期
[markup.goldmark.renderer]
unsafe = true
最近更新的文章在展示时，默认只展示 3 篇，可以在 layouts\partials\recent.html 中修改
<div class="content-list">
<h2></h2>
<!-- 改成 6 篇 -->
</div>
发布
使用 [[ vercel ]]托管，这里坑较多
[[ vercel ]]部署 [[ Hugo ]]时默认版本为 0.58 ，非常旧，相对的本地的版本是 0.113
这里需要在 vercel.json 中配置环境变量 HUGO_VERSION 指定版本
[!INFO] 指定版本 文档藏的很深Deployment Environments | Vercel Docs
// vercel.json { "build": { "env": { "HUGO_VERSION": "0.113.0" } } }
该方案的作者特地写了一个插件jackyzha0/hugo-obsidian来生成双向链接，该插件需要 [[ Golang ]]环境才能安装 [[ vercel ]]并没有提供该环境，这里需要定制buildCommand来手动安装环境然后打包
// vercel.json
{
"buildCommand": "sh ./flat.sh && curl -L https://git.io/vQhTU | bash -s -- --version 1.20.5 && source /vercel/.bashrc && go install github.com/jackyzha0/hugo-obsidian@latest && hugo-obsidian -input=content -output=assets/indices -index -root=. && ls && hugo --minify",
"build": {
"env": {
"HUGO_VERSION": "0.113.0"
}
}
}
这一大坨命令执行流程如下：
- 拍平文章，执行
sh ./flat.sh#!/bin/bash mv content/*/*/*.md content/ mv content/Home.md content/_index.md # 将 Home 设置为主页 - 使用canha/golang-tools-install-script安装 [[ Golang ]]环境
curl -L https://git.io/vQhTU | bash -s -- --version 1.20.5 source /vercel/.bashrc # 更新环境变量 - 安装jackyzha0/hugo-obsidian并生成双向链接
go install github.com/jackyzha0/hugo-obsidian@latest hugo-obsidian -input=content -output=assets/indices - 使用 [[ Hugo ]]生成静态站点
hugo --minify
编写文章
标题
文章标题内不能含有 .
否则反向链接与关系图谱会生成失败
标签
在给文章的 [[ Formatter ]]中上标签时，**标签必须为标准的 [[ YAML#数组 ]]**
如果像这样写标签
---
tags: 标签A, 标签B
---
Obsidian可以识别，但该部署方案的解析器会解析失败（hugo-obsidian 元数据解析问题），这将导致页面的元数据丢失，具体表现为
正确的写法参考 [[ YAML#数组 ]]
quartz 方案
对比 [[ #Hugo 方案 ]]：
- 不需要拍平文章（我为了让以前的链接不失效还是排平了）
- 使用node.js生态，方便定制
- 部署步骤简单，没有Hugo那一堆有的没的坑
如需部署到 [[ vercel ]]，往仓库里新增两个文件：
-
flat.sh：
#!/bin/bash
# 下面这行用于拍平文章，可有可无
mv content/*/*/*.md content/
# 我的主页是 Home.md，需要转成 index.md
mv content/Home.md content/index.md
-
vercel.json：
{
"installCommand": "npm install",
"buildCommand": "sh ./flat.sh && npx quartz build",
"cleanUrls": true
}
然后去项目设置中将 node 版本设置为 18.x：
同步子仓库
如果使用了 [[ Git 子模块 ]]来关联Obsidian工作区，此时需要定时拉取子模块仓库的代码到发布仓库中，这里直接通过 [[ Github Action ]]来解决
name: 'Submodules Sync'
on:
schedule:
- cron: '0 2 * * *'
# Allows you to run this workflow manually from the Actions tab or through HTTP API
workflow_dispatch:
jobs:
sync:
name: 'Submodules Sync'
runs-on: ubuntu-latest
# Use the Bash shell regardless whether the GitHub Actions runner is ubuntu-latest, macos-latest, or windows-latest
defaults:
run:
shell: bash
steps:
# Checkout the repository to the GitHub Actions runner
- name: Checkout
uses: actions/checkout@v2
with:
token: $
submodules: true
# Update references
- name: Git Sumbodule Update
run: |
git pull --recurse-submodules
git submodule update --remote --recursive
- name: Commit update
run: |
git config --global user.name 'Git bot'
git config --global user.email 'bot@noreply.github.com'
git remote set-url origin https://x-access-token:$@github.com/$
git commit -am "Auto updated submodule references" && git push || echo "No changes to commit"
需要给予 [[ Github Action ]]读写权限，否则该工作流将无法同步子仓库
