Obsidian

fumadocs-obsidian 提供執行階段的內容來源。它會直接讀取並編譯 vault，因此不會產生中介的 MDX 檔案，也不需要 Fumadocs MDX 的 remark 外掛。

支援的 Obsidian 語法包括：

Wikilink 與嵌入。
Callout。
區塊 ID。
註解。

名稱有歧義的 wikilink 會比照 Obsidian 的方式解析：筆記優先於附件，其次以路徑最短者為準。未知語言 (例如 dataview) 的程式碼區塊會以純文字算繪。

設定

安裝套件：

npm install fumadocs-obsidian shiki

產生樣式

fumadocs-obsidian/ui 中的元件使用 Tailwind CSS 撰寫樣式。請加入以下這行，以產生這些元件所需的 class：

Tailwind CSS

@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';
@import 'fumadocs-obsidian/css/preset.css';

設定來源

建立 Obsidian 來源，並將它傳入 dynamicLoader()：

lib/source.ts

import { dynamicLoader } from 'fumadocs-core/source';
import { obsidian } from 'fumadocs-obsidian';

const vault = obsidian({
  dir: 'public/vault',
  // 將 vault 附件對應到其公開 URL
  url: (path) => `/vault/${path}`,
});

const vaultLoader = dynamicLoader(vault.dynamicSource(), {
  baseUrl: '/docs',
});

export function getSource() {
  return vaultLoader.get();
}

此範例將 vault 放在 public/vault，讓您的框架能透過 url 回傳的 URL 提供附件。若您的應用程式會另行提供或上傳附件，也可以將 vault 放在其他位置。

接著載入並算繪頁面。page.data.load() 會回傳已編譯頁面的算繪器。

app/docs/[[...slug]]/page.tsx

import { getSource } from '@/lib/source';
import { notFound } from 'next/navigation';
import defaultMdxComponents, { createRelativeLink } from 'fumadocs-ui/mdx';
import * as ObsidianComponents from 'fumadocs-obsidian/ui';
import { DocsBody, DocsPage } from 'fumadocs-ui/layouts/docs/page';

export default async function Page({ params }: PageProps<'/docs/[[...slug]]'>) {
  const source = await getSource();
  const page = source.getPage((await params).slug);
  if (!page) notFound();

  const { body, toc } = await (
    await page.data.load()
  ).render({
    ...defaultMdxComponents,
    ...ObsidianComponents,
    a: createRelativeLink(source, page),
  });

  return (
    <DocsPage toc={toc}>
      <DocsBody>{body}</DocsBody>
    </DocsPage>
  );
}

在同一個 vault 快照中，page.data.load() 對每個頁面最多只會編譯一次。Vault 內容會以純 Markdown 編譯：算繪時只會將其對應為 JSX 並解析元件名稱，因此內容中的 JavaScript 一律不會執行。媒體檔案透過 URL 參照，不會讀入記憶體。

熱重載

開發期間，請在應用程式旁同時執行內建的內容監看器：

package.json

{
  "scripts": {
    "dev": "fumadocs-obsidian dev -- next dev"
  }
}

將 vault 連接至監看器：

lib/source.ts

if (process.env.NODE_ENV === 'development') {
  void vault.devServer();
}

由於 Wikilink 與別名可能會在檔案之間產生相依關係，因此任何一處變更都會讓整個來源快照失效。

靜態來源

若 vault 只需讀取一次，請使用 staticSource()：

lib/source.ts

import { loader } from 'fumadocs-core/source';
import { obsidian } from 'fumadocs-obsidian';

const vault = obsidian({
  dir: 'public/vault',
  url: (path) => `/vault/${path}`,
});

export const source = loader(await vault.staticSource(), {
  baseUrl: '/docs',
});

Schema

您可以使用相容於 Standard Schema 的驗證器，自訂頁面的 frontmatter 與 meta.json 檔案：

lib/source.ts

import { frontmatterSchema, obsidian } from 'fumadocs-obsidian';
import { metaSchema } from 'fumadocs-core/source/schema';
import { z } from 'zod';

const vault = obsidian({
  dir: 'public/vault',
  frontmatterSchema: frontmatterSchema.extend({
    tags: z.array(z.string()).optional(),
  }),
  metaSchema,
});

預設的 frontmatterSchema 能容許結構較鬆散的 vault：像 title: 2024 這類純量標題會自動轉換為字串，而 aliases 可接受單一名稱，也可接受清單。未通過驗證的筆記會被回報並略過，不會影響 vault 中的其他內容。

額外功能

如需啟用個別語法功能，請另外傳入對應的 remark/rehype 外掛：

Mermaid。
數學公式。

lib/source.ts

import { obsidian } from 'fumadocs-obsidian';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

const vault = obsidian({
  dir: 'public/vault',
  remarkPlugins: [remarkMath],
  rehypePlugins: [rehypeKatex],
});

設定複製錨點連結

產生樣式複製錨點連結

設定來源複製錨點連結

熱重載複製錨點連結

靜態來源複製錨點連結

Schema複製錨點連結

額外功能複製錨點連結

本頁目錄

設定

產生樣式

設定來源

熱重載

靜態來源

Schema

額外功能