本機 Markdown

簡介複製錨點連結

@fumadocs/local-md 是用於本機 Markdown/MDX 檔案的內容來源。它在設計上採用免打包 (bundleless) 架構，因此能完全在執行階段運作。

與 MDX Remote 相比，它專注於本機檔案，並負責處理流程中更多的環節 (frontmatter、meta 檔案、搜尋索引) 。

與 Astro 內容集合相比，它會在執行階段編譯您的內容，而非透過打包工具處理，因此無法使用建置階段的圖片最佳化。

限制複製錨點連結

• 不支援建置階段的圖片最佳化。
• MDX 檔案中不支援匯入／匯出，但您可以在算繪時傳入元件。

設定複製錨點連結

安裝套件：

npm install @fumadocs/local-md shiki

建立 localMd 實例，並將其連接至 Fumadocs：

import { dynamicLoader } from 'fumadocs-core/source';
import { localMd } from '@fumadocs/local-md';

const docs = localMd({
  dir: 'content/docs',
  // 選項
});

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

export async function getSource() {
  return docsLoader.get();
}

Schema複製錨點連結

您可以傳入 frontmatterSchema 與 metaSchema，以自訂驗證用的 schema：

import { localMd } from '@fumadocs/local-md';
import { pageSchema, metaSchema } from 'fumadocs-core/source/schema';

const docs = localMd({
  dir: 'content/docs',
  frontmatterSchema: pageSchema.extend({
    // ...
  }),
  metaSchema: metaSchema.extend({
    // ...
  }),
});

使用方式複製錨點連結

getSource() 會回傳一般的內容載入器。每個頁面都有 page.data.load()，它會編譯該頁面並回傳一個算繪器 (renderer) 。

在頁面中將其序列化，再於 React island 中算繪：

---
import type { GetStaticPaths, InferGetStaticPropsType } from 'astro';
import Layout from '@/layouts/Layout.astro';
import { Docs } from '@/components/docs';
import { getSource } from '@/lib/source';

export const prerender = true;

export const getStaticPaths = (async () => {
  const source = await getSource();
  return source.getPages().map((page) => ({
    params: { slug: decodeURI(page.slugs.join('/')) || undefined },
    props: { page },
  }));
}) satisfies GetStaticPaths;

type Props = InferGetStaticPropsType<typeof getStaticPaths>;

const { page } = Astro.props;
const source = await getSource();
const pageTree = await source.serializePageTree(source.getPageTree());
const { serialize } = await page.data.load();
---

<Layout title={page.data.title}>
  <Docs
    client:load
    pathname={Astro.url.pathname}
    params={Astro.params}
    tree={pageTree}
    title={page.data.title}
    render={serialize()}
  />
</Layout>

引入複製錨點連結

<include> 預設為啟用狀態：

<include>../shared/note.md</include>

在 Markdown 檔案中，請先設定好 remark-directive，再使用 ::include[../shared/note.md] 指令：

import remarkDirective from 'remark-directive';

const docs = localMd({
  dir: 'content/docs',
  mdOptions: { remarkPlugins: [remarkDirective] },
});

熱重載複製錨點連結

@fumadocs/local-md 在執行階段讀取檔案，因此預設不會監看任何檔案。

開發期間，Vite 外掛會透過 Vite 的檔案監看器讓來源失效，不需要額外的處理程序或連接埠。請將外掛加入您的設定，並連接來源：

import { defineConfig } from 'astro/config';
import { localContentPlugin } from '@fumadocs/local-md/dev/vite';

export default defineConfig({
  vite: {
    plugins: [localContentPlugin()],
  },
});

由於內容檔案位於模組圖之外，外掛會將您的內容目錄加入 Vite 的監看器。由於沒有任何模組失效，外掛會改為直接重新載入瀏覽器。若要自行處理重新載入，請傳入 localContentPlugin({ reload: false })。

當 Markdown 或 MDX 檔案 (包括其引入的檔案) 變更時，來源就會重新載入。若要串接自訂的監看器，請監看 docs.dir 以及傳入 docs.onDependency() 的檔案，並在檔案變更時呼叫 docs.invalidateFile(path)。

JavaScript 引擎複製錨點連結

MDX 檔案 (*.mdx) 會透過 new Function 執行，因此在禁止使用 eval() 的環境中 (例如 Cloudflare Workers) 無法運作。

Markdown 檔案 (*.md) 會直接從語法樹算繪，不需要 eval()。外掛產生的 JSX 則由內建的虛擬 JavaScript 引擎進行求值，您可以透過 rendererOptions.executor 替換此引擎。

停用重新驗證複製錨點連結

staticSource() 會回傳一次性的快照，不會重新驗證。它需搭配 loader() 使用，而非 dynamicLoader()：

import { loader } from 'fumadocs-core/source';
import { localMd } from '@fumadocs/local-md';

const docs = localMd({
  dir: 'content/docs',
});

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