ドキュメント貢献ガイド

Next.js ドキュメント貢献ガイドへようこそ！あなたの参加を心から歓迎します。

このページでは、Next.js ドキュメントを編集する方法について説明します。私たちの目標は、コミュニティの誰もがドキュメントの改善に貢献できるようにすることです。

なぜ貢献するのか？

オープンソースの仕事は決して終わることがありません。ドキュメントも同様です。ドキュメントへの貢献は、オープンソース初心者が参加する良いきっかけとなり、経験豊富な開発者が複雑なトピックを明確にしながら知識をコミュニティと共有する機会にもなります。

Next.js ドキュメントに貢献することで、すべての開発者にとってより堅牢な学習リソースの構築を支援することになります。タイポを見つけた場合、わかりにくいセクションがあった場合、特定のトピックが不足していることに気付いた場合、どんな貢献でも歓迎され、感謝されます。

貢献方法

ドキュメントのコンテンツは Next.js リポジトリ にあります。貢献するには、GitHub 上で直接ファイルを編集するか、リポジトリをクローンしてローカルでファイルを編集できます。

GitHub ワークフロー

GitHub が初めての方は、GitHub オープンソースガイド を読んで、リポジトリのフォーク、ブランチの作成、プルリクエストの提出方法を学ぶことをお勧めします。

豆知識: ドキュメントの基盤となるコードはプライベートなコードベースにあり、Next.js 公開リポジトリに同期されています。つまり、ドキュメントをローカルでプレビューすることはできません。ただし、プルリクエストをマージした後、nextjs.org で変更を確認できます。

MDX の書き方

ドキュメントは MDX 形式で書かれています。これは JSX 構文をサポートするマークダウン形式で、ドキュメント内に React コンポーネントを埋め込むことができます。マークダウン構文の概要については GitHub マークダウンガイド を参照してください。

VSCode

ローカルでの変更プレビュー

VSCode には組み込みのマークダウンプレビューアがあり、ローカルで編集内容を確認できます。MDX ファイルのプレビューアを有効にするには、ユーザー設定に構成オプションを追加する必要があります。

コマンドパレット（Mac では ⌘ + ⇧ + P、Windows では Ctrl + Shift + P）を開き、Preferences: Open User Settings (JSON) を検索します。

次に、settings.json ファイルに次の行を追加します：

{
  "files.associations": {
    "*.mdx": "markdown"
  }
}

再度コマンドパレットを開き、Markdown: Preview File または Markdown: Open Preview to the Side を検索します。これにより、フォーマットされた変更を確認できるプレビューウィンドウが開きます。

拡張機能

VSCode ユーザーには以下の拡張機能もお勧めします：

• MDX: MDX のインテリセンスとシンタックスハイライト
• Prettier: 保存時に MDX ファイルをフォーマット

レビュープロセス

貢献を提出すると、Next.js または Developer Experience チームが変更をレビューし、フィードバックを提供し、準備が整ったらプルリクエストをマージします。

質問がある場合やさらなる支援が必要な場合は、PR のコメントでお知らせください。Next.js ドキュメントに貢献し、私たちのコミュニティの一員になってくださり、ありがとうございます！

ヒント: PR を提出する前に pnpm prettier-fix を実行して Prettier を実行しましょう。

ファイル構造

ドキュメントは ファイルシステムルーティング を使用しています。/docs 内の各フォルダとファイルはルートセグメントを表します。これらのセグメントは URL パス、ナビゲーション、パンくずリストの生成に使用されます。

ファイル構造はサイト上で見えるナビゲーションを反映しており、デフォルトではナビゲーション項目はアルファベット順にソートされます。ただし、フォルダまたはファイル名の前に2桁の数字（00-）を付けることで、項目の順序を変更できます。

例えば、functions API Reference では、特定の関数を簡単に見つけられるようにページはアルファベット順にソートされています：

04-functions
├── after.mdx
├── cacheLife.mdx
├── cacheTag.mdx
└── ...

しかし、routing セクション では、開発者がこれらの概念を学ぶべき順序でソートするために、ファイルに2桁の数字が付けられています：

01-routing
├── 01-defining-routes.mdx
├── 02-pages.mdx
├── 03-layouts-and-templates.mdx
└── ...

ページを素早く見つけるには、VSCode で ⌘ + P（Mac）または Ctrl + P（Windows）を使用して検索バーを開きます。その後、探しているページのスラグを入力します。例：defining-routes

なぜマニフェストを使用しないのか？

マニフェストファイル（ドキュメントナビゲーションを生成する別の人気のある方法）の使用も検討しましたが、マニフェストはファイルとすぐに同期が取れなくなることがわかりました。ファイルシステムルーティングは、ドキュメントの構造について考えることを強制し、Next.js によりネイティブに感じられます。

メタデータ

各ページには、上部に3つのダッシュで区切られたメタデータブロックがあります。

必須フィールド

以下のフィールドは 必須 です：

---
title: ページタイトル
description: ページの説明
---

ページタイトルは2-3語（例：画像の最適化）に制限し、説明は1-2文（例：Next.js で画像を最適化する方法を学びましょう）にするのが良い習慣です。

オプションフィールド

以下のフィールドは オプション です：

---
nav_title: ナビゲーション項目タイトル
source: app/building-your-application/optimizing/images
related:
  description: 画像コンポーネントの API リファレンスを参照してください。
  links:
    - app/api-reference/components/image
version: experimental
---

App と Pages ドキュメント

App Router と Pages Router の機能のほとんどは完全に異なるため、それぞれのドキュメントは別々のセクション（02-app と 03-pages）に分かれています。ただし、いくつかの機能は両者で共有されています。

共有ページ

コンテンツの重複を避け、コンテンツが同期されなくなるリスクを減らすために、source フィールドを使用して1つのページから別のページにコンテンツを取り込みます。例えば、<Link> コンポーネントは App と Pages で ほぼ 同じように動作します。コンテンツを重複させる代わりに、app/.../link.mdx から pages/.../link.mdx にコンテンツを取り込むことができます：

---
title: <Link>
description: <Link> コンポーネントの API リファレンス。
---

この API リファレンスは、Link コンポーネントで利用可能な props
と設定オプションの使用方法を理解するのに役立ちます。

---
title: <Link>
description: <Link> コンポーネントの API リファレンス。
source: app/api-reference/components/link
---

{/* このページは編集しないでください。 */}
{/* このページのコンテンツは上記のソースから取り込まれています。 */}

これにより、1か所でコンテンツを編集し、両方のセクションに反映させることができます。

共有コンテンツ

共有ページでは、App Router または Pages Router に固有のコンテンツがある場合があります。例えば、<Link> コンポーネントには Pages でのみ利用可能で App では利用できない shallow prop があります。

コンテンツが正しいルーターでのみ表示されるようにするために、コンテンツブロックを <AppOnly> または <PagesOnly> コンポーネントでラップできます：

このコンテンツは App と Pages で共有されます。

<PagesOnly>

このコンテンツは Pages ドキュメントでのみ表示されます。

</PagesOnly>

このコンテンツは App と Pages で共有されます。

これらのコンポーネントは、例やコードブロックに使用することが多いでしょう。

コードブロック

コードブロックには、コピー＆ペーストできる最小限の動作例を含める必要があります。つまり、コードは追加の設定なしで実行できる必要があります。

例えば、<Link> コンポーネントの使用方法を示す場合、import ステートメントと <Link> コンポーネント自体を含める必要があります。

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">About</Link>
}

コミットする前に、必ず例をローカルで実行してください。これにより、コードが最新で動作することを確認できます。

言語とファイル名

コードブロックには、言語と filename を含むヘッダーが必要です。filename プロップを追加すると、ユーザーがコマンドを入力する場所を案内する特別なターミナルアイコンが表示されます。例えば：

```bash filename="Terminal"
npx create-next-app
```

ドキュメントのほとんどの例は tsx と jsx で書かれており、いくつかは bash で書かれています。ただし、サポートされている任意の言語を使用できます。完全なリストは こちら です。

JavaScript コードブロックを書く場合、以下の言語と拡張子の組み合わせを使用します。

豆知識:

• JavaScript ファイルで JSX コードを使用する場合は、必ず js 拡張子を使用してください。
• 例：```jsx filename="app/layout.js"

TS と JS スイッチャー

TypeScript と JavaScript を切り替える言語スイッチャーを追加します。コードブロックは TypeScript を優先し、JavaScript バージョンも用意してユーザーに対応します。

現在、TS と JS の例を連続して書き、switcher プロップでリンクしています：

```tsx filename="app/page.tsx" switcher

```

```jsx filename="app/page.js" switcher

```

豆知識: 将来的には TypeScript スニペットを自動的に JavaScript にコンパイルする予定です。それまでは、transform.tools を使用できます。

行のハイライト

コード行をハイライトできます。これはコードの特定の部分に注意を引きたい場合に便利です。highlight プロップに数値を渡すことで行をハイライトできます。

単一行: highlight={1}

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">About</Link>
}

複数行: highlight={1,3}

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">About</Link>
}

行の範囲: highlight={1-5}

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">About</Link>
}

アイコン

ドキュメントで使用可能なアイコンは以下の通りです：

<Check size={18} />
<Cross size={18} />

出力:

ドキュメントでは絵文字を使用しません。

注記

重要だが必須ではない情報には注記を使用します。注記は、メインコンテンツからユーザーを邪魔せずに情報を追加する良い方法です。

> **豆知識**: これは1行の注記です。

> **豆知識**:
>
> - 複数行の注記にもこの形式を使用します。
> - 知っておくべきことや覚えておくべきことが複数ある場合があります。

出力:

豆知識: これは1行の注記です。

豆知識:

• 複数行の注記にもこの形式を使用します。
• 知っておくべきことや覚えておくべきことが複数ある場合があります。

関連リンク

関連リンクは、ユーザーの学習の流れを導くために、論理的な次のステップへのリンクを追加します。

• リンクはメインコンテンツの下にカード形式で表示されます。
• 子ページがあるページには自動的にリンクが生成されます。

ページのメタデータ内の related フィールドを使用して関連リンクを作成します。

---
related:
  description: 最初のアプリケーションをすぐに開始する方法を学びましょう。
  links:
    - app/building-your-application/routing/defining-routes
    - app/building-your-application/data-fetching
    - app/api-reference/file-conventions/page
---

ネストされたフィールド

ダイアグラム

ダイアグラムは複雑な概念を説明するのに最適です。ダイアグラムの作成には Figma を使用し、Vercel のデザインガイドに従います。

現在、ダイアグラムはプライベートな Next.js サイトの /public フォルダにあります。ダイアグラムを更新または追加したい場合は、GitHub イシュー にアイデアを提出してください。

カスタムコンポーネントと HTML

ドキュメントで利用可能な React コンポーネントは以下の通りです：<Image /> (next/image)、<PagesOnly />、<AppOnly />、<Cross />、<Check />。<details> タグ以外の生の HTML はドキュメントで許可されていません。

新しいコンポーネントのアイデアがある場合は、GitHub イシュー を開いてください。

スタイルガイド

このセクションには、技術文書を書くのが初めての方のためのガイドラインが含まれています。

ページテンプレート

ページに厳密なテンプレートはありませんが、ドキュメント全体で繰り返し見られるページセクションがあります：

• 概要: ページの最初の段落では、機能が何であり、何に使用されるかをユーザーに伝えます。その後、最小限の動作例またはその API リファレンスを示します。
• 規約: 機能に規約がある場合は、ここで説明します。
• 例: 機能をさまざまなユースケースで使用する方法を示します。
• API テーブル: API ページには、可能な場合はセクションへのジャンプリンクを含む概要テーブルをページの最後に配置します。
• 次のステップ（関連リンク）: ユーザーの学習の流れを導くために、関連ページへのリンクを追加します。

必要に応じてこれらのセクションを自由に追加してください。

ページの種類

ドキュメントのページは「概念説明」と「APIリファレンス」の2つのカテゴリに分かれています。

• 概念説明ページは、概念や機能を説明するために使用されます。通常、リファレンスページよりも長く、より多くの情報を含みます。Next.jsドキュメントでは、概念説明ページはアプリケーションの構築セクションにあります。
• APIリファレンスページは、特定のAPIを説明するために使用されます。通常より短く、焦点が絞られています。Next.jsドキュメントでは、APIリファレンスページはAPIリファレンスセクションにあります。

豆知識: 貢献するページによって、異なる文体やスタイルを使い分ける必要があるかもしれません。例えば、概念説明ページはより指導的で、ユーザーに直接語りかける「あなた」という言葉を使います。リファレンスページはより技術的で、「作成する、更新する、受け入れる」などの命令形の言葉を使い、「あなた」という言葉を省略する傾向があります。

文体

ドキュメント全体で一貫したスタイルと文体を維持するためのガイドラインです:

• 明確で簡潔な文章を書く。脱線を避ける。
  • コンマを多用していると感じたら、文章を複数に分割するかリストを使うことを検討してください。
  • 複雑な言葉をよりシンプルな言葉に置き換える。例えば「utilize」ではなく「use」を使う。
• 「これ」という言葉には注意。曖昧で混乱を招く可能性があるため、不明確な場合はためらわずに文の主語を繰り返す。
  • 例: 「Next.js uses React」ではなく「Next.js uses this」
• 受動態ではなく能動態を使う。能動態の文章は読みやすい。
  • 例: 「React is used by Next.js」ではなく「Next.js uses React」。もし「was」や「by」のような言葉を使っている場合、受動態を使っている可能性がある。
• 「簡単」「すぐ」「単純」「ただ」などの言葉は避ける。これは主観的で、ユーザーを落胆させる可能性がある。
• 「しない」「できない」「しないだろう」などの否定的な言葉は避ける。読者を落胆させる可能性がある。
  • 例: 「ページ間のリンクを作成するにはLinkコンポーネントを使用できます」ではなく「ページ間のリンクを作成するのに<a>タグを使わないでください」
• 二人称（あなた/あなたの）で書く。より個人的で親しみやすい。
• 性別に中立な言葉を使う。読者を指す場合は「開発者」「ユーザー」「読者」などを使う。
• コード例を追加する場合は、適切にフォーマットされ動作することを確認する。

これらのガイドラインは完全なものではありませんが、始めるのに役立つはずです。技術文書作成についてさらに深く学びたい場合は、Google Technical Writing Courseを参照してください。

ドキュメントへの貢献とNext.jsコミュニティへの参加、ありがとうございます！