跳至主要内容

[Docusaurus] Obsidian 整合指南

將 Obsidian 和 Docusaurus 整合，以 Obsidian 作為編輯器編寫文章及建立知識庫，同時利用 Docusaurus 作為客製化發佈工具。

專案結構 (Source Tree)​

Docusaurus 設定彈性很大，唯一限制是專案必須有 docs 資料夾，且裡面至少要有一個 .md 檔案，否則會報錯如下：

❯ rm -rf docs
❯ yarn start
yarn run v1.22.19
$ docusaurus start
[INFO] Starting the development server...
[ERROR] Error: The docs folder does not exist for version "current". A docs folder is expected to be found at docs.
    at getVersionMetadataPaths (/Users/kywk/.node_modules/docusaurus/node_modules/@docusaurus/plugin-content-docs/lib/versions/files.js:123:15)
    at async createVersionMetadata (/Users/kywk/.node_modules/docusaurus/node_modules/@docusaurus/plugin-content-docs/lib/versions/index.js:97:68)
    at async Promise.all (index 0)
    at async readVersionsMetadata (/Users/kywk/.node_modules/docusaurus/node_modules/@docusaurus/plugin-content-docs/lib/versions/index.js:150:30)
    at async Object.pluginContentDocs [as plugin] (/Users/kywk/.node_modules/docusaurus/node_modules/@docusaurus/plugin-content-docs/lib/index.js:32:30)
    at async initializePlugin (/Users/kywk/.node_modules/docusaurus/node_modules/@docusaurus/core/lib/server/plugins/init.js:83:32)
    at async Promise.all (index 0)
    at async initPlugins (/Users/kywk/.node_modules/docusaurus/node_modules/@docusaurus/core/lib/server/plugins/init.js:91:21)
    at async loadPlugins (/Users/kywk/.node_modules/docusaurus/node_modules/@docusaurus/core/lib/server/plugins/index.js:26:21)
    at async load (/Users/kywk/.node_modules/docusaurus/node_modules/@docusaurus/core/lib/server/index.js:76:58)
[INFO] Docusaurus version: 2.2.0
Node version: v16.17.1
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

個人專案檔案結構如下，可以看出同時包含 Docusaurus 專案結構以及其他 Obsidian 文章：

❯ tree -a -d -L 2
.
├── .docusaurus
│   ├── ...
│   └── docusaurus-plugin-wikigraph
├── .git
├── .github
│   └── workflows
├── .obsidian
│   ├── plugins
│   └── themes
├── _incoming
│   ├── archive
│   └── sandbox
├── _journaling
│   ├── 2023
│   └── 2024
├── _templates
│   └── scripts
├── assets
├── backpacker
│   ├── ...
│   ├── 2401 Egypt
│   ├── Around World
│   └── PIWIW
├── blog.life
│   ├── ...
│   └── 2024
├── blog.news
│   ├── ...
│   └── 2024
├── com.XXXX
│   ├── xxx
│   └── zip_archive
├── docs
├── important
├── lifehacker
│   ├── ...
│   └── taiwan
├── moco
│   ├── ...
│   └── utilities
├── src
│   ├── components
│   ├── css
│   └── pages
└── static
    └── img
```

## Docusaurus 配置

如前所述，Docusaurus 設定彈性很大，只要指定到正確路徑即可：

```typescript
// 建立共用的 remark 插件配置
function createRemarkPlugins(fileMap, routeBase) {
  return [
    [remarkKanban, { pageResolver: createPageResolver(fileMap), hrefTemplate: (permalink) => `${routeBase}${permalink}/` }],
    [remarkWikiLink, {
      pageResolver: createPageResolver(fileMap),
      hrefTemplate: (permalink) => `${routeBase}${permalink}/`,
    }],
  ];
}

// 在 plugins 中使用
plugins: [
  [
    '@docusaurus/plugin-content-docs',
    {
      id: 'moco',
      path: 'moco',
      routeBasePath: 'moco',
      remarkPlugins: createRemarkPlugins(mocoFileMap, '/moco/'),
      sidebarPath: require.resolve('./sidebars.js'),
    },
  ],
  [
    '@docusaurus/plugin-content-blog',
    {
      id: 'news',
      routeBasePath: 'news',
      path: 'blog.news',
      showReadingTime: true,
    },
  ],
],

Kanban、Tasks 與 Mermaid theme 目前以 npm 套件提供（03 Obsidian 外掛 Kanban 與 Tasks、02 docusaurus-theme-pele 與 Mermaid 遷移）；新專案直接安裝套件即可，不需要複製站內 plugins/。

Git 版本控制 (.gitignore)​

常見 Docusaurus 發佈到 GitHub 有兩種方式：

  1. 手動發佈: 本地端手動 yarn build 之後手動把整個 build 資料夾上傳到伺服器
  2. 自動化部署: 配置 GitHub Actions，專案 push 上去後觸發 CI/CD，讓 GitHub 處理建置和發佈

第二種方式工作流程較為順暢方便。且若偶爾在沒有 Node.js 環境工作，只要能 push 上 GitHub，都可以持續發佈更新網站。

但因專案裡同時包含透過 Obsidian 所管理的個人資料，好好配置 .gitignore 避免個人資料不小心放上 GitHub 是相當重要的。

依實際需求把 Obsidian 專案設定和重要個人資料和工作資料加入 .gitignore 即可：

# Obsidian folder
.obsidian/
assets/

# Personal & Working folder
com.A/
com.B/
important/
project/
temporary.md

Obsidian 實際排除設定​

目前 Obsidian 的排除設定儲存在 .obsidian/app.json 的 userIgnoreFilters，內容是：

[
  "node_modules/",
  "plugins/",
  "scripts/",
  "src/",
  "static/",
  "build/",
  ".docusaurus/",
  ".git/"
]

這些路徑不會被 Obsidian 納入一般檔案瀏覽與索引工作。.obsidian/ 的設定檔則保留給 Obsidian 自己使用。修改排除清單時，應同步檢查 Docusaurus build 是否仍能讀到必要的 moco/ 文章與 assets/。

技巧與稍門 (Tips & Tricks)​

Docusaurus 草稿功能​

隨著 Obsidian 的使用，在 Docusaurus 相關目錄下可能會建立讓 Obsidian 管理的檔案，例如把 Obsidian 當 Task Manager 的話，會建立 Kanban.md、TODO.md 之類的檔案。

這些檔案內容若不想跟著 Docusaurus 一起發佈出去，可以在 frontmatter 加上 draft: true。例如 moco/Obsidian/Obsidian as PKM.md 目前就是草稿，因此不應視為已發布的使用指南。

總結與展望​

第一階段的整合算是完成，後續隨著深入使用 Obsidian，預計會再折騰一番，以打造量身製作的知識平台。

已完成功能​

開發中功能​

  • ignore Obsidian tags - 忽略 Obsidian 標籤語法
  • support obsidian dataview queries - 支援 Dataview 查詢語法