Notion

はじめにアンカーリンクをコピー

@fumadocs/notion を使うと、Notion データベースを Fumadocs のコンテンツソースとして利用できます。公式の Notion API 経由でページを取得する動的なコンテンツソースと、Notion のブロックを Fumadocs UI でレンダリングするサーバーレンダラーを提供します。

クライアントサイドのレンダラーは含まれておらず、コンテンツを MDX に変換することもありません。ブロックはサーバー上でレンダリングされるため、バンドラーや型生成のステップは不要です。

セットアップアンカーリンクをコピー

インテグレーションと公式の Notion クライアントをインストールします。

npm install @fumadocs/notion @notionhq/client

Fumadocs UI のスタイルの後に、レンダラーの Tailwind CSS ソースをインポートしてください：

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

NOTION_TOKEN=ntn_...
NOTION_DATA_SOURCE_ID=...

import { Client } from '@notionhq/client';
import { createNotion } from '@fumadocs/notion';

export const notion = createNotion({
  client: new Client({ auth: process.env.NOTION_TOKEN }),
  dataSourceId: process.env.NOTION_DATA_SOURCE_ID!,
});

import { dynamicLoader } from 'fumadocs-core/source';
import { notion } from '@/lib/notion';

const source = dynamicLoader(
  notion.dynamicSource({
    // Notion のプロパティをページのフィールドにマッピングします
    properties: {
      title: 'Name',
      slug: 'Slug',
      description: 'Description',
    },
    // フィルタリングや並べ替えなど、クエリを自由にカスタマイズします
    query: {
      filter: {
        property: 'Published',
        checkbox: { equals: true },
      },
    },
  }),
  {
    baseUrl: '/docs',
  },
);

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

import type { ReactNode } from 'react';
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import { getSource } from '@/lib/source';

export default async function Layout({ children }: { children: ReactNode }) {
  const source = await getSource();

  return <DocsLayout tree={source.getPageTree()}>{children}</DocsLayout>;
}

import { createNotionFileHandler } from '@fumadocs/notion';
import { notion } from '@/lib/notion';

export const GET = createNotionFileHandler(notion);

createNotionFileUrlResolver({ pageId: page.data.id, path: '/notion/file' });

再検証アンカーリンクをコピー

ローダーは、キャッシュを無効化するまでページをキャッシュし続けます。Notion での編集内容を反映するには、信頼できる Webhook または再検証用のルートから revalidate() を呼び出してください。

export function revalidateNotion() {
  return source.revalidate();
}

すべてのリクエストで最新のコンテンツを反映させるプレビュー向けの構成では、読み込む前にキャッシュを無効化してください。

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

ページプロパティアンカーリンクをコピー

properties は、Notion のプロパティをページのフィールドにマッピングします。省略した場合、ソースは次のように動作します。

• 最初の Notion title プロパティをページタイトルとして使用します。
• Slug という名前のプロパティを URL に使用します。存在しない場合は、タイトルから生成したスラッグにフォールバックします。
• Description という名前のプロパティがあれば、それを使用します。

スラッグに / を含めると、ネストされたルートを作成できます。仮想パスが重複している場合や安全でない場合は、ページを暗黙的に置き換えるのではなく、内容がわかるエラーを出して失敗します。

クエリとパスアンカーリンクをコピー

Notion のフィルターとソートは query で渡します。仮想ページを特定のディレクトリ配下に配置するには baseDir を、仮想ファイルのパスを完全に制御するには generatePath を使用します。

notion.dynamicSource({
  baseDir: 'docs',
  query: {
    sorts: [{ timestamp: 'last_edited_time', direction: 'descending' }],
  },
  generatePath(page, info) {
    return info.slugs.length > 0 ? `${info.slugs.join('/')}.mdx` : `${page.id}.mdx`;
  },
});

レンダリングのカスタマイズアンカーリンクをコピー

NotionRenderer には、一般的なブロックタイプ用のレンダラーが組み込まれています。components を渡すと、レンダラーを追加または上書きできます。上書きするレンダラーには、それぞれ対応するブロックに応じた型が付きます。

import { NotionRenderer } from '@fumadocs/notion';

<NotionRenderer
  blocks={blocks}
  components={{
    callout({ block, children, renderRichText }) {
      return (
        <aside className="rounded-lg bg-fd-muted p-4">
          {renderRichText(block.callout.rich_text)}
          {children}
        </aside>
      );
    },
  }}
/>;

コードブロックは、デフォルトでサーバー側で Shiki によってハイライトされます。ハイライトせずにプレーンなコードとしてレンダリングするには highlightCode={false} を、独自のハイライターを組み込むには関数を渡してください。

ソースのみのインポートアンカーリンクをコピー

検索インデクサーや llms.txt ルートなど、Notion ページを取得するだけのコードでは、@fumadocs/notion/source からインポートすることで、React レンダラーのエントリーを読み込まずに済みます：

import { createNotion } from '@fumadocs/notion/source';

このエントリーポイントでは Notion SDK を外部依存として扱い、React のインポートは一切含みません。blocksToPlainText()、blocksToStructuredData()、blocksToTableOfContents() もこちらから利用できます。