Tinyrack Docs · Tinyrack Design System

Tinyrack Docs は、MDX と TSX ファイルから、ナビゲーション、検索、言語別ページ、 SEO アセット、Tinyrack UI を備えた静的な React Router ドキュメントサイトを構築します。このガイドでは、空のプロジェクトから本番ビルドまでを説明します。 Node.js 24 以降が必要です。

1. パッケージをインストールする

React 19 と React Router 8 とともにドキュメントランタイムをインストールしてください。React Router、Tailwind CSS 4、Vite のビルドツールは開発依存関係に追加します。

pnpm add @tinyrack/docs @tinyrack/ui react react-dom react-router
pnpm add --save-dev @react-router/dev @tailwindcss/vite tailwindcss vite

2. サイトを設定する

プロジェクトルートに docs.config.ts を作成してください。contentDir はドキュメントルートを格納するディレクトリを指定します。セクション名とサイトのメタデータは、ナビゲーションと生成される SEO アセットにも使われます。

import { defineDocsConfig } from '@tinyrack/docs/config';

export default defineDocsConfig({
  contentDir: 'app/content',
  i18n: {
    defaultLocale: 'en',
    locales: {
      en: { label: 'English', language: 'en', openGraph: 'en_US' },
      ko: { label: '한국어', language: 'ko', openGraph: 'ko_KR' },
    },
  },
  redirects: { '/': '/en/' },
  sections: [
    { id: 'start', label: { en: 'Start', ko: '시작하기' }, order: 0 },
    { id: 'guides', label: { en: 'Guides', ko: '가이드' }, order: 1 },
  ],
  site: {
    basePath: '/',
    description: 'Documentation for this project.',
    favicon: '/favicon.svg',
    locale: { language: 'en', openGraph: 'en_US' },
    logo: { dark: '/logo-inverse.svg', light: '/logo.svg' },
    title: 'Project Docs',
    url: 'https://docs.example.com',
  },
  theme: { default: 'auto' },
});

theme.default には auto、light、dark を指定できます。auto は OS のカラースキームに従います。ヘッダーで選択した値は設定した既定値より優先され、次回のアクセス時にも維持されます。

ロゴとファビコンは public/ に配置してください。ドメインルートではなく /docs などのサブパスで配信する場合は、site.basePath を変更します。

3. React Router と Vite を接続する

React Router のルート定義とフレームワーク設定を作成してください。両方が同じ Docs 設定を使うため、ルートの検出と静的出力が一致します。

// app/routes.ts
import { createDocsRoutes } from '@tinyrack/docs/react-router';
import config from '../docs.config.js';

export default createDocsRoutes(config);

// react-router.config.ts
import { createDocsRouterConfig } from '@tinyrack/docs/react-router';
import config from './docs.config.js';

export default createDocsRouterConfig(config);

Tinyrack Docs プラグインを Tailwind CSS プラグインより前に登録してください。

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
import { tinyrackDocs } from '@tinyrack/docs/vite';
import { defineConfig } from 'vite';
import config from './docs.config.js';

export default defineConfig({
  plugins: [...tinyrackDocs(config), tailwindcss()],
});

生成されたすべてのルートにドキュメントシェル、メタデータ、Tinyrack テーマを適用するため、パッケージのルートとスタイルシートを使ってください。

/* app/styles/tinyrack-docs.css */
@import "@tinyrack/docs/styles.css";

// app/root.tsx
import './styles/tinyrack-docs.css';

export { default, Layout, links, meta } from '@tinyrack/docs/runtime';

4. MDX ページを追加する

contentDir 以下のすべての .mdx と .tsx ファイルは、再帰的にルートになります。app/content/en/getting-started.mdx を作成すると、ファイル名が /en/getting-started/ に対応します。ページのタイトルと説明は Tinyrack Docs が表示するため、本文の見出しはレベル 2 から始めてください。

---
title: "Getting started"
description: "Install and configure the project."
section: start
order: 0
---

## Install

Install the package with your package manager.

order は省略できます。order を指定したページがセクション内で先に並び、残りのページはサイドバーラベルのアルファベット順で続きます。

インポートするコンポーネント、例、ヘルパーは contentDir の外に配置してください。このディレクトリ内の補助ファイルも、別のドキュメントルートとして扱われます。

5. TSX ページを追加する

ルートに独自の React 構成が必要な場合は DocsPage を使ってください。 app/content/en/status.tsx は /en/status/ に対応します。

import { DocsPage } from '@tinyrack/docs/runtime';

export default function StatusPage() {
  return (
    <DocsPage
      frontmatter={{
        title: 'Status',
        description: 'Review the current service status.',
        section: 'guides',
        order: 0,
      }}
      headings={[{ depth: 2, id: 'services', label: 'Services' }]}
    >
      <h2 id="services">Services</h2>
      <p>All systems are operational.</p>
    </DocsPage>
  );
}

frontmatter と任意の headings は、静的なインラインオブジェクトリテラルで指定する必要があります。ルート検出時には、変数、スプレッド、計算された値、関数呼び出し、テンプレート式を読み取れません。宣言したすべての見出し id は、実際に表示する見出しと一致させてください。

6. サイトを実行してビルドする

package.json に React Router のコマンドを追加してください。

{
  "scripts": {
    "dev": "react-router dev",
    "build": "react-router build",
    "preview": "vite preview"
  }
}

pnpm dev を実行し、生成された MDX と TSX のルートを開いてください。サイドバーのリンクとページ内目次がコンテンツに合っていることを確認してから、pnpm build を実行します。本番ビルドでは、静的ルート、リダイレクト、Pagefind 検索インデックス、サイトマップ、robots ファイル、ソーシャル画像などの SEO アセットが生成されます。 pnpm preview でビルド結果をローカルで確認できます。

7. ナビゲーションとロケールを調整する

ロケールディレクトリ以下で相対パスが同じファイルは、互いの言語別ページになります。この設定例では、en/getting-started.mdx と ko/getting-started.mdx が対応します。英語、韓国語、日本語のインターフェース文言が組み込まれており、必要な場合はロケールごとに一部の文言を上書きできます。

標準のサイドバーは、セクションから構成されます。セクション内では order を指定したページが先に並び、残りはサイドバーラベルのアルファベット順で並びます。セクション設定で groups を宣言し、ページの frontmatter に group を指定すると、折りたたみ可能なサブグループにまとめられます。明示的なグループや外部リンクが必要な場合は、再帰的な navigation 設定を使ってください。ヘッダーのパスに /{locale} を含めると、内部リンクで現在の言語を維持できます。 MDX では追加設定なしで CommonMark、GFM、コードハイライト、:::caution などの callout directive を利用できます。

Tinyrack Docs には、プロジェクトジェネレーター、専用 CLI、ランタイム MDX コンパイラー、デプロイサービスは含まれません。デプロイ設定は利用するプロジェクトで管理し、対象ホストで本番ビルドを確認してください。

ドキュメントサイトではなくプロダクトアプリケーションに Tinyrack UI を追加する場合は、インストールを参照してください。既存のアプリケーションで信頼できる MDX を表示する場合は、MDX コンポーネントマップを使ってください。