🧠 缸中大脑

Search

SearchSearch

发布

Dec 28, 2023, 8 min read

jekyll 方案

无意间看到的教程obsidian 目前最完美的免费发布方案 - 渐进式教程 — 🌱 oldwinterの数字花园

部署过程中几乎没坑，就算是小白也能大概跑通，需要配置 Ruby 环境

Hugo 方案

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](Installation | Hugo (gohugo.io))和 hugo-obsidian 在项目根目录中执行 go install github.com/jackyzha0/hugo-obsidian@latest 即可完成 hugo-obsidian 的安装

最后在项目根目录中执行 make serve 来启动开发服务，默认端口为 1313，具体看命令行输出

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>{{ i18n "recent_notes" }}</h2>
  {{$notes := .Site.RegularPages.ByLastmod.Reverse}}
  <!-- 改成 6 篇 -->
  {{partial "page-list.html" (first 6 $notes)}}
</div>

发布

使用vercel托管，这里坑较多

vercel部署Hugo时默认版本为 0.58 ，非常旧，相对的本地的版本是 0.113 这里需要在 vercel.json 中配置环境变量 HUGO_VERSION 指定版本

指定版本

文档藏的很深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中上标签时，==标签必须为标准的数组==

如果像这样写标签

---
tags: 标签A, 标签B
---

Obsidian可以识别，但该部署方案的解析器会解析失败（hugo-obsidian 元数据解析问题），这将导致页面的元数据丢失，具体表现为

正确的写法参考数组

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: ${{ secrets.GITHUB_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:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
          git commit -am "Auto updated submodule references" && git push || echo "No changes to commit"

需要给予Github Action读写权限，否则该工作流将无法同步子仓库

Graph View

Backlinks