静态站点生成
将 Obsidian 笔记发布为静态博客或文档站点，是分享知识的好方式。本文介绍几种主流的发布方案。
方案对比
| 方案 | 难度 | 自定义程度 | 适用场景 |
|---|---|---|---|
| Obsidian Publish | ⭐ | ⭐⭐ | 快速发布 |
| Hugo + 插件 | ⭐⭐⭐ | ⭐⭐⭐⭐ | 技术博客 |
| MkDocs | ⭐⭐ | ⭐⭐⭐ | 文档站点 |
| VitePress | ⭐⭐ | ⭐⭐⭐⭐ | 技术文档 |
| Jekyll | ⭐⭐ | ⭐⭐⭐ | GitHub Pages |
方案一：Obsidian Publish
Obsidian 官方的发布服务，最简单但需要付费。
使用步骤
- 设置 → 核心插件 → 启用 "发布"
- 点击发布图标
- 选择要发布的笔记
- 点击 "发布"
优点
- ✅ 零配置
- ✅ 实时同步
- ✅ 保持 Obsidian 格式
- ✅ 支持密码保护
缺点
- ❌ 每月 $8 起
- ❌ 自定义有限
- ❌ 依赖官方服务
方案二：Hugo 发布
Hugo 是最快的静态站点生成器，适合技术博客。
准备工作
- 安装 Hugo：
brew install hugo(macOS) - 安装 "Obsidian to Hugo" 插件
目录结构
Vault/
├── content/ # Hugo 内容
│ ├── posts/
│ └── about.md
├── static/ # 静态资源
├── themes/ # 主题
└── config.toml # 配置配置示例
config.toml
toml
baseURL = "https://yourdomain.com"
languageCode = "zh-cn"
title = "我的知识库"
theme = "PaperMod"
[params]
defaultTheme = "auto"
ShowReadingTime = true
[markup]
[markup.goldmark]
[markup.goldmark.renderer]
unsafe = true处理 Obsidian 特有格式
创建脚本处理双链：
python
import re
def convert_wikilinks(content):
# [[链接]] → [链接](/链接/)
pattern = r'\[\[(.*?)\]\]'
return re.sub(pattern, r'[\1](/\1/)', content)发布到 GitHub Pages
yaml
# .github/workflows/deploy.yml
name: Deploy
on:
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: peaceiris/actions-hugo@v2
- run: hugo --minify
- uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./public方案三：VitePress 发布
VitePress 是 Vue 驱动的静态站点生成器，适合技术文档。
初始化项目
bash
npm init vitepress配置文件
.vitepress/config.mts
typescript
import { defineConfig } from 'vitepress'
export default defineConfig({
title: "知识库",
description: "我的数字花园",
themeConfig: {
nav: [
{ text: '首页', link: '/' },
{ text: '笔记', link: '/notes/' }
],
sidebar: [
{
text: '笔记',
items: [
{ text: '入门', link: '/notes/getting-started' }
]
}
]
}
})Markdown 增强
VitePress 支持丰富的 Markdown 扩展：
markdown
::: tip 提示
这是一个提示框
:::
::: warning 警告
这是一个警告框
:::方案四：数字花园方案
Quartz
Quartz 是专为 Obsidian 设计的发布工具。
bash
npx quartz create特点：
- 原生支持 Obsidian 格式
- 双链渲染
- 图谱视图
- 全文搜索
Garden
另一个数字花园方案：
bash
git clone https://github.com/mathieudutour/garden.git
npm install
npm start处理常见问题
双链转换
Obsidian 的 [[链接]] 需要转换为标准 Markdown：
python
# Python 脚本
import re
import os
def convert_vault(vault_path):
for root, dirs, files in os.walk(vault_path):
for file in files:
if file.endswith('.md'):
filepath = os.path.join(root, file)
with open(filepath, 'r') as f:
content = f.read()
# 转换双链
content = re.sub(
r'\[\[(.*?)\]\]',
r'[\1](/\1/)',
content
)
with open(filepath, 'w') as f:
f.write(content)图片处理
- 复制图片到静态目录
- 更新图片路径
python
# 更新图片路径
content = re.sub(
r'!\[\[(.*?)\]\]',
r'',
content
)Front Matter 处理
确保 Front Matter 格式正确：
yaml
---
title: 文章标题
date: 2024-02-15
tags:
- tag1
- tag2
draft: false
---自动化部署流程
GitHub Actions 完整示例
yaml
name: Deploy Blog
on:
push:
branches: [main]
schedule:
- cron: '0 0 * * *' # 每天自动部署
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
- name: Install dependencies
run: npm ci
- name: Build
run: npm run build
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./dist推荐主题
Hugo 主题
- PaperMod：简洁现代
- Stack：卡片风格
- Anubis：极简设计
VitePress 主题
- 默认主题：功能完整
- 自定义主题：完全可控
版本要求
版本说明
- Hugo：推荐 0.100+
- VitePress：推荐 1.0+
- Node.js：推荐 18+