APIリファレンス

Markdownとして表示 GitHubで編集ドキュメント: 7b38e05

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のUIDocsPageをラップし、コンテンツを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のUIDocsPageの他の任意の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 - 機能とフッターの間に表示するコンテンツ（任意）

設定で制御できる内容については、ホームページとフッターを参照してください。

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",
};

すべてのオプションについては設定を参照してください。

ソースユーティリティ

loader

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

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）。修正されるまでは、上記のように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.jsMetadataオブジェクト:

タイトル（config.title）とタイトルテンプレート（%s | Site Name）
説明
設定されている場合、config.iconのファビコン
baseUrlが設定されている場合: metadataBase、OpenGraphメタデータ、Twittersummary_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画像を参照してください。

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と検索を参照してください。

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と検索を参照してください。

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は含まれていません。使用するには、コンポーネントの説明に従って自分で追加してください。

使用例についてはコンポーネントを参照してください。