# APIリファレンス

`onedocs`パッケージからのすべてのエクスポートを網羅したリファレンスです。

## エントリーポイント

| インポート | 説明 |
|--------|-------------|
| `onedocs` | メインエントリー - レイアウト、コンポーネント、`mdxComponents`、`defineConfig`、ソースヘルパー |
| `onedocs/components` | Fumadocs UIコンポーネントと、`InstallBlock`、`CodeBlock`、`Button`、`Logo` |
| `onedocs/config` | 設定ヘルパー |
| `onedocs/source` | コンテンツソースユーティリティ |
| `onedocs/metadata` | メタデータ生成 |
| `onedocs/og` | OpenGraph画像生成 |
| `onedocs/llms` | LLMs.txt生成 |
| `onedocs/seo` | サイトマップとrobots.txt |
| `onedocs/css/preset.css` | Tailwind CSSプリセット |

## レイアウト

### DocsLayout

ドキュメントページのメインレイアウトラッパーです。サイドバーのナビゲーション、検索、テーマ切り替えを提供します。

```tsx
import { DocsLayout } from "onedocs";

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <DocsLayout config={config} pageTree={source.pageTree}>
      {children}
    </DocsLayout>
  );
}
```

**Props:**
- `config` - 使用する`OnedocsConfig`オブジェクト
- `pageTree` - ソースのページツリー（e.g、`source.pageTree`など）
- `children` - ページコンテンツ

### DocsPage

個々のドキュメントページ用のラッパーです。FumadocsのUI`DocsPage`をラップし、コンテンツを`DocsBody`に配置します。

```tsx
import { DocsPage, mdxComponents } from "onedocs";
import { notFound } from "next/navigation";

export default async function Page(props: {
  params: Promise<{ slug?: string[] }>;
}) {
  const params = await props.params;
  const page = source.getPage(params.slug);
  if (!page) notFound();
  const MDX = page.data.body;

  return (
    <DocsPage toc={page.data.toc}>
      <MDX components={mdxComponents} />
    </DocsPage>
  );
}
```

**Props:**
- `toc` - ページデータの目次
- `children` - MDXコンテンツ
- FumadocsのUI`DocsPage`の他の任意のprop（`full`など）

### DocsBody

ドキュメントコンテンツ用の内部ボディラッパーです。内部で`DocsPage`が使用します。

```tsx
import { DocsBody } from "onedocs";

<DocsBody>
  <MDX components={mdxComponents} />
</DocsBody>
```

### HomePage

ヒーロー、機能、フッターを含むランディングページ全体のコンポーネントです。

```tsx
import { HomePage, CTASection } from "onedocs";

export default function Home() {
  return (
    <HomePage config={config} packageName="my-package">
      <CTASection
        title="Ready to get started?"
        cta={{ label: "Read the Docs", href: "/docs" }}
      />
    </HomePage>
  );
}
```

**Props:**
- `config` - 使用する`OnedocsConfig`オブジェクト
- `packageName` - インストールブロックに表示するパッケージ名（任意）
- `children` - 機能とフッターの間に表示するコンテンツ（任意）

設定で制御できる内容については、[ホームページ](https://onedocs.inline0.dev/ja/docs/configuration#homepage)と[フッター](https://onedocs.inline0.dev/ja/docs/configuration#footer)を参照してください。

### HomeLayout

ホームページの基本レイアウトです（内部で`HomePage`が使用）。

```tsx
import { HomeLayout } from "onedocs";

<HomeLayout config={config}>
  {/* Custom homepage content */}
</HomeLayout>
```

### createBaseOptions

設定からFumadocsのUIレイアウトオプション（ナビバーのタイトルまたはロゴ、`nav.links`、GitHubリンク）を構築します。`DocsLayout`と`HomeLayout`はこれを使用します。FumadocsのUIレイアウトを直接レンダリングする場合は、自分で呼び出してください。

```tsx
import { DocsLayout } from "fumadocs-ui/layouts/docs";
import { createBaseOptions } from "onedocs";

<DocsLayout {...createBaseOptions(config)} tree={source.pageTree}>
  {children}
</DocsLayout>
```

## コンポーネント

### InstallBlock

npm、yarn、pnpm、bun（`npm i`、`yarn add`、`pnpm add`、`bun add`）のインストールコマンドを表示するパッケージマネージャーのタブです。非同期サーバーコンポーネントです。

```tsx
import { InstallBlock } from "onedocs";

<InstallBlock packageName="onedocs" />
```

**Props:**
- `packageName` - インストールするnpmパッケージ名
- `title` - タブ上部の見出し（任意）
- `description` - タブ上部のテキスト（任意）
- `children` - タブ下部のコンテンツ（任意）

### Button

プライマリボタンのスタイルを適用した角丸リンクです。スタイルは1種類です。

```tsx
import { Button } from "onedocs";

<Button href="/docs">Get Started</Button>
```

**Props:**
- `href` - リンク先
- `children` - ボタンのテキスト
- `className` - 追加クラス（任意）

### Logo

ライト用とダーク用の画像を表示し、現在のテーマに合う方を表示します。`DocsLayout`と`HomePage`は、ライト用とダーク用のバリエーションを備えた`logo`に使用します。

```tsx
import { Logo } from "onedocs";

<Logo light="/logo-light.svg" dark="/logo-dark.svg" alt="My Project" className="h-6" />
```

**Props:**
- `light` - ライトモード用の画像パス
- `dark` - ダークモード用の画像パス
- `alt` - 代替テキスト（デフォルト: `"Logo"`）
- `className` - 両方の画像に適用するクラス（任意）

### CTASection

ホームページの行動喚起セクションです。

```tsx
import { CTASection } from "onedocs";

<CTASection
  title="Ready to get started?"
  description="Optional description text"
  cta={{ label: "Get Started", href: "/docs" }}
/>
```

**Props:**
- `title` - セクションの見出し
- `description` - 見出し下のテキスト（任意）
- `cta` - `label`と`href`を含むボタン設定
- `children` - ボタン下のコンテンツ（任意）

### FontHead

Inter Variableフォントを先読みし、その`@font-face`を宣言してページのフォントに設定します。ルートレイアウトの`<head>`に追加します。

```tsx
import { FontHead } from "onedocs";

<html>
  <head>
    <FontHead />
  </head>
  <body>{children}</body>
</html>
```

Onedocsにはフォントが含まれていません。デフォルトでは`FontHead`が`/fonts/InterVariable.woff2`を読み込むため、ファイルを`public/fonts/`に配置するか、`fontPath`を指定した別のURLを渡してください:

```tsx
<FontHead fontPath="/assets/Inter.woff2" />
```

### GitHubIcon

GitHubアイコンのコンポーネントです（内部でナビゲーションに使用）。

```tsx
import { GitHubIcon } from "onedocs";

<GitHubIcon className="size-5" />
```

### CodeBlock

Fumadocsを通じてShikiでサーバー側の構文ハイライトを行うコードブロックです。非同期サーバーコンポーネントです。

```tsx
import { CodeBlock } from "onedocs";

<CodeBlock lang="tsx" code="const x = 1;" />
```

## 設定

### defineConfig

型安全な設定ヘルパーです。

```tsx
import { defineConfig } from "onedocs/config";

export default defineConfig({
  title: "My Docs",
  // ... other options
});
```

### OnedocsConfig

設定用のTypeScript型です。

```tsx
import type { OnedocsConfig } from "onedocs/config";

const config: OnedocsConfig = {
  title: "My Docs",
};
```

すべてのオプションについては[設定](https://onedocs.inline0.dev/ja/docs/configuration)を参照してください。

## ソースユーティリティ

### loader

コンテンツソースを作成する`fumadocs-core/source`loaderの再エクスポートです。

```tsx
import { loader } from "onedocs/source";

export const source = loader({
  baseUrl: "/docs",
  source: docs.toFumadocsSource(),
});
```

### createSource

コンテンツソースを作成するヘルパーです（loaderのラッパー）。ベースのURLはデフォルトで`/docs`になります。

```tsx
import { createSource } from "onedocs/source";
import { docs } from "../../.source/server";

export const source = createSource(docs);
// export const source = createSource(docs, { baseUrl: "/guide" });
```

0.1.27では`createSource`が型なしのソースを返すため、`page.data`の読み取り時に`Property 'data' does not exist on type 'unknown'`などのエラーがTypeScriptから報告されます（[#4](https://github.com/inline0/onedocs/issues/4)）。修正されるまでは、上記のように`loader`を使用してください。

## メタデータ

### createMetadata

ルートレイアウト用のNext.jsメタデータを生成します。

```tsx
import { createMetadata } from "onedocs/metadata";

export const metadata = createMetadata(config, {
  baseUrl: "https://example.com",
});
```

**Options:**
- `baseUrl` - サイトのベースURL（任意）
- `additional` - 最後にマージされる追加の`Metadata`フィールド（任意）

**Returns:** 次の内容を含むNext.js`Metadata`オブジェクト:
- タイトル（`config.title`）とタイトルテンプレート（`%s | Site Name`）
- 説明
- 設定されている場合、`config.icon`のファビコン
- `baseUrl`が設定されている場合: `metadataBase`、OpenGraphメタデータ、Twitter`summary_large_image`カード

### createDocsPageMetadata

ドキュメントページのタイトルと説明のメタデータを生成します。`title`と任意の`description`を含む1つのオブジェクトを受け取ります。

```tsx
import { createDocsPageMetadata } from "onedocs/metadata";
import { notFound } from "next/navigation";

export async function generateMetadata(props: {
  params: Promise<{ slug?: string[] }>;
}) {
  const params = await props.params;
  const page = source.getPage(params.slug);
  if (!page) notFound();

  return createDocsPageMetadata({
    title: page.data.title,
    description: page.data.description,
  });
}
```

ページごとのOpen Graph画像については、[動的OG画像](#dynamic-og-images)を参照してください。

## OpenGraph画像

### createRootOGImage

ホームページ用のOG画像を作成します。黒い背景の中央にロゴを配置します。

```tsx
// src/app/opengraph-image.tsx
import {
  createRootOGImage,
  loadPublicFile,
  ogImageSize,
  ogImageContentType,
  type OGImageLogo,
} from "onedocs/og";

export const size = ogImageSize;
export const contentType = ogImageContentType;

export default async function Image() {
  const logo = await loadPublicFile("logo-dark.svg");
  return createRootOGImage(logo as OGImageLogo);
}
```

### createDocsOGImage

ドキュメントページ用のOG画像を作成します。左上にロゴを置き、白いタイトルを黒い背景に表示します。フォント引数は任意で、省略するとシステムフォントでタイトルを表示します。

```tsx
// src/app/docs/opengraph-image.tsx
import {
  createDocsOGImage,
  loadPublicFile,
  loadInterFont,
  ogImageSize,
  ogImageContentType,
  type OGImageLogo,
} from "onedocs/og";

export const size = ogImageSize;
export const contentType = ogImageContentType;

export default async function Image() {
  const [logo, font] = await Promise.all([
    loadPublicFile("logo-dark.svg"),
    loadInterFont(),
  ]);
  return createDocsOGImage("Documentation", logo as OGImageLogo, font);
}
```

### 動的OG画像

ページごとのOG画像を使うには、ルートから配信します。ページからこのルートへの参照は自動で設定されないため、たとえば`createDocsPageMetadata`のフィールドと並べて`openGraph: { images: "/docs/og/getting-started" }`を指定するなど、各ページのメタデータに自分で追加してください。

```tsx
// src/app/docs/og/[...slug]/route.tsx
import {
  createDocsOGImage,
  loadPublicFile,
  loadInterFont,
  type OGImageLogo,
} from "onedocs/og";
import { source } from "@/lib/source";

export async function GET(
  _request: Request,
  { params }: { params: Promise<{ slug: string[] }> }
) {
  const { slug } = await params;
  const page = source.getPage(slug);
  const title = page?.data.title ?? "Documentation";

  const [logo, font] = await Promise.all([
    loadPublicFile("logo-dark.svg"),
    loadInterFont(),
  ]);

  return createDocsOGImage(title, logo as OGImageLogo, font);
}
```

### ヘルパー関数

| 関数 | 説明 |
|----------|-------------|
| `loadPublicFile(path)` | `public/`からファイルをデータURLとバッファとして読み込みます。SVGの場合は`width`属性と`height`属性も読み込みます |
| `loadInterFont(path?)` | OG画像用のフォントを`public/`から読み込みます。デフォルトは`fonts/Inter-Medium.ttf`です |
| `ogImageSize` | 標準OG画像のサイズ`{ width: 1200, height: 630 }` |
| `ogImageContentType` | MIME型`"image/png"` |

**必須ファイル:**
- `public/logo-dark.svg` - OG画像用のロゴです。OGヘルパーは`width`属性と`height`属性からサイズを取得するため、`<svg>`タグには両方を数値で指定する必要があります。
- `public/fonts/Inter-Medium.ttf` - タイトル用のフォントです。Onedocsには含まれていません。

## LLMs.txt

AIアシスタント用のLLMs.txtファイルを生成します。

### generateLLMsText

簡潔なLLMs.txtコンテンツを生成します。`createLLMsSource`と`{ title, description? }`でラップされたソースを受け取り、Promiseを返します。

```tsx
// src/app/llms.txt/route.ts
import { createLLMsSource, generateLLMsText } from "onedocs/llms";
import { source } from "@/lib/source";

export async function GET() {
  const content = await generateLLMsText(createLLMsSource(source), {
    title: "My Project",
    description: "Project description",
  });

  return new Response(content, {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}
```

ページURLは、ドメインを含めず、`/docs/getting-started`のようにソースの内容に沿って記述されます。

### generateLLMsFullText

ページコンテンツ全体を含む完全なLLMs.txtを生成します。ラップ済みソースだけを受け取り、Promiseを返します。

```tsx
// src/app/llms-full.txt/route.ts
import { createLLMsSource, generateLLMsFullText } from "onedocs/llms";
import { source } from "@/lib/source";

export async function GET() {
  const content = await generateLLMsFullText(createLLMsSource(source));

  return new Response(content, {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}
```

ページ本文が含まれるのは、FumadocsMDXの`includeProcessedMarkdown`が有効な場合のみです。[SEOと検索](https://onedocs.inline0.dev/ja/docs/seo-search#full-content-version)を参照してください。

### createLLMsSource

Fumadocsのソース（`loader()`または`createSource()`の結果）を、上記2つの関数が読み取る形式でラップします。各ページのURL、タイトル、説明、テキストローダーを含みます。

## SEO

### generateSitemap

ドキュメントのサイトマップを生成します。`baseUrl`、`meta.json`から取得することが多い`pages`リスト、任意の`docsPath`（デフォルトは`/docs`）を含むオブジェクトを1つ受け取ります。

```tsx
// src/app/sitemap.ts
import { generateSitemap } from "onedocs/seo";
import meta from "../../content/docs/meta.json";

export default function sitemap() {
  return generateSitemap({
    baseUrl: "https://example.com",
    pages: meta.pages ?? [],
  });
}
```

エントリーがURLになる仕組みについては、[SEOと検索](https://onedocs.inline0.dev/ja/docs/seo-search#sitemap)を参照してください。

### generateRobots

robots.txtコンテンツを生成します。すべてを許可し、`Host`と`Sitemap`の行を加えます。`sitemapPath`のデフォルトは`/sitemap.xml`です。

```tsx
// src/app/robots.ts
import { generateRobots } from "onedocs/seo";

export default function robots() {
  return generateRobots({
    baseUrl: "https://example.com",
  });
}
```

## CSSプリセット

`globals.css`でCSSプリセットをインポートします:

```css
@import "onedocs/css/preset.css";

@source "./**/*.tsx";
@source "../../content/**/*.mdx";
```

`@source`のパスは`src/app/globals.css`からの相対パスです。

プリセットには次のものが含まれます:
- Tailwind CSS v4（`tailwindcss`と`@tailwindcss/postcss`は自分でインストール）
- Fumadocsのニュートラルテーマ
- Fumadocsのプリセットスタイル
- `--font-sans`を`FontHead`が定義する`--font-inter`変数に設定
- 本文と見出し向けのInter OpenType機能
- 全高レイアウトのスタイルとOnedocsのレイアウト調整

## MDXコンポーネント

`mdxComponents`エクスポートはFumadocsのUIのデフォルトMDXコンポーネントをすべて含み、以下のコンポーネントを追加します:

```tsx
import { mdxComponents } from "onedocs";

<MDX components={mdxComponents} />
```

**含まれるコンポーネント:**
- FumadocsUIのデフォルト: `pre`（コードブロック）、`a`、`img`、アンカー付き見出しの`h1`から`h6`、`table`、`CodeBlockTab`、`CodeBlockTabs`、`CodeBlockTabsList`、`CodeBlockTabsTrigger`、`CalloutContainer`、`CalloutTitle`、`CalloutDescription`
- `Callout` - 情報・警告・エラーのコールアウト
- `Card`、`Cards` - カードレイアウト
- `Tab`、`Tabs` - タブ付きコンテンツ
- `Step`、`Steps` - 番号付き手順
- `Accordion`、`Accordions` - 折りたたみセクション
- `File`、`Folder`、`Files` - ファイルツリー
- `ImageZoom` - 拡大可能な画像
- `TypeTable` - 型ドキュメント用テーブル

`InstallBlock`と`CodeBlock`は含まれていません。使用するには、[コンポーネント](https://onedocs.inline0.dev/ja/docs/components#more-components)の説明に従って自分で追加してください。

使用例については[コンポーネント](https://onedocs.inline0.dev/ja/docs/components)を参照してください。