ドキュメントの作成

このガイドでは、ファイル構造の理解から効果的なコンテンツの記述まで、新しいドキュメントファイルを作成するプロセスを順を追って説明します。

ファイル構造と命名規則

ディレクトリ構成

ドキュメントは階層構造で整理されています：

src/content/docs/[lang]/[version]/[category]/[document].mdx

パスの例：

src/content/docs/en/v2/guide/creating-documents.mdx
src/content/docs/ja/v2/components/icons.mdx
src/content/docs/en/v2/advanced/customization.mdx

命名規則

ファイル名にはケバブケースを使用：creating-documents.mdx
順序付けのために数字を含める：01-getting-started.mdx、02-creating-documents.mdx
説明的で簡潔に：sidebar.mdxではなくsidebar-auto-generation.mdx

作成スクリプトの使用

新しいドキュメントを作成する最も簡単な方法は、組み込みスクリプトを使用することです：

node scripts/create-document.js [project-name] [lang] [version] [slug]

例

# 英語版ガイドドキュメントを作成
node scripts/create-document.js sample-docs en v2 guide/installation

# 日本語版コンポーネント例を作成
node scripts/create-document.js sample-docs ja v2 components/buttons

# 上級設定ガイドを作成
node scripts/create-document.js sample-docs en v2 advanced/custom-themes

スクリプトの動作

作成スクリプトは自動的に以下を行います：

ファイルの作成 - 適切なディレクトリ構造で
最小限のフロントマターの生成 - タイトルと説明付き
コンテンツテンプレートの提供 - 開始のサポート
自動整理の処理 - ファイル命名と構造を通じて

手動でのドキュメント作成

手動でドキュメントを作成したい場合は、以下の手順に従ってください：

1. ファイルの作成

適切なディレクトリに新しい.mdxファイルを作成：

touch src/content/docs/ja/v2/guide/my-new-guide.mdx

2. フロントマターの追加

すべてのドキュメントは最小限のYAMLフロントマターで始まる必要があります：

---
title: "私の新しいガイド"
description: "このガイドが扱う内容の説明"
---

このシステムは整理とナビゲーションに自動アプローチを使用するため、タイトルと説明のみが必要です。

3. コンテンツの記述

MarkdownとMDXを使用してコンテンツを追加：

# 私の新しいガイド

これがガイドのメインコンテンツです。

## セクション見出し

ここにコンテンツが入ります...

### サブセクション

より詳細なコンテンツ...

フロントマターリファレンス

必須フィールド

フィールド	型	説明
`title`	string	ドキュメントタイトル（ナビゲーションとページヘッダーに表示）
`description`	string	SEOとプレビュー用の簡潔な説明（50-160文字推奨）

自動機能

このドキュメントシステムは以下を自動的に処理します：

ナビゲーション：ファイル構造に基づく前/次リンク
分類：ディレクトリ名から（01-guide、02-componentsなど）
順序付け：ファイル名の接頭辞から（01-、02-など）
メタデータ：Gitヒストリーからの公開・更新日

コンテンツガイドライン

文体

会話的に：同僚に説明するように書く
能動態を使用：「ファイルを作成してください」（「ファイルが作成されるべきです」ではなく）
具体的に：正確なコマンド、ファイル名、パスを含める
文脈を追加：なぜ重要なのかを説明

構造のベストプラクティス

概要から始める：読者が学ぶことは何か？
明確な見出しを使用：論理的なコンテンツ階層を作成
例を含める：実用的な応用を示す
次のステップで終わる：読者を前進させる

コード例

動作するコード例を含める：

// 良い例：完全で動作する例
import { createApp } from '@our-package/core';

const app = createApp({
  debug: true,
  theme: 'dark'
});

app.start();

画像とアセット

publicディレクトリに画像を保存：

![代替テキスト](/images/screenshot.png)

ドキュメントのテスト

最終化する前に確認：

フロントマターが有効：YAML構文エラーなし
リンクが機能：すべての内部・外部リンクが機能的
コードが動作：コード例が実際に動作
ナビゲーションの流れ：前/次リンクが論理的な進行を作成
フォーマット：ヘッダー、リスト、強調が正しく表示

一般的なパターン

ステップバイステップガイド

---
title: "パッケージインストールガイド"
description: "コアパッケージのインストールと検証方法を学ぶ"
---

# パッケージインストールガイド

パッケージをインストールするには以下の手順に従ってください：

## ステップ1：前提条件

Node.js 18+がインストールされていることを確認：

    node --version

## ステップ2：パッケージのインストール

インストールコマンドを実行：

    npm install @our-package/core

## ステップ3：インストールの確認

インストールが成功したことを確認：

    npm list @our-package/core

リファレンスドキュメント

---
title: "APIリファレンス"
description: "コアライブラリの完全なAPIドキュメント"
---

# APIリファレンス

## `createApp(options)`

新しいアプリケーションインスタンスを作成します。

**パラメータ：**
- `options` (Object): 設定オプション
  - `debug` (boolean): デバッグモードを有効化
  - `theme` (string): UIテーマ（'light' | 'dark'）

**戻り値：** アプリケーションインスタンス

**例：**
    const app = createApp({ debug: true });

次のステップ

ドキュメントの作成方法を理解したら、以下について学びましょう：

ドキュメントの編集：コンテンツの編集と更新のベストプラクティス
コンテンツの整理：ドキュメントの構造化と分類方法
コンポーネントの使用：インタラクティブな要素でドキュメントを強化