ドキュメント貢献ガイド

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

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

なぜ貢献するのか？

オープンソースの作業は終わりがなく、ドキュメントも同様です。ドキュメントへの貢献は、初心者がオープンソースに関わる良い方法であり、経験豊富な開発者にとっては複雑なトピックを明確にしながら、コミュニティと知識を共有する機会となります。

Next.jsドキュメントに貢献することで、すべての開発者にとってより充実した学習リソースの構築に協力することになります。誤字を見つけた場合でも、わかりにくいセクションがあった場合でも、特定のトピックが不足していると気づいた場合でも、あなたの貢献は歓迎され感謝されます。

貢献方法

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

GitHubワークフロー

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

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

MDXの記述

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

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リファレンスでは、開発者が特定の関数を見つけやすくするため、ページはアルファベット順に並べられています：

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

しかし、ルーティングセクションでは、ファイルの先頭に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語（例：Optimizing Images）に制限し、説明は1〜2文（例：Next.jsでの画像の最適化方法について学ぶ）にするのが良い習慣です。

オプションフィールド

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

---
nav_title: ナビ項目タイトル
source: /docs/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: /docs/app/api-reference/components/link
---
 
{/* このページは編集しないでください。 */}
{/* このページの内容は上記のソースから取り込まれています。 */}

これにより、一箇所でコンテンツを編集すれば、両方のセクションに反映されます。

共有コンテンツ

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

コンテンツが正しいルーターにのみ表示されるようにするには、コンテンツブロックを<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
---

ネストされたフィールド

図表

図表は複雑な概念を説明するのに最適な方法です。私たちはVercelのデザインガイドに従ってFigmaで図表を作成しています。

現在、図表はプライベートのNext.jsサイトの/publicフォルダにあります。図表を更新または追加したい場合は、アイデアをGitHub issueで開いてください。

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

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

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

スタイルガイド

このセクションには、技術文書初心者向けのドキュメント作成ガイドラインが含まれています。

ページテンプレート

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

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

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

ページタイプ

ドキュメントページは、概念的なページと参照ページの2つのカテゴリに分かれています。

• 概念的ページは、概念や機能を説明するために使用されます。通常、参照ページよりも長く、より多くの情報が含まれています。Next.jsドキュメントでは、概念的ページはBuilding Your Applicationセクションにあります。
• 参照ページは、特定のAPIを説明するために使用されます。通常、より短く、焦点が絞られています。Next.jsドキュメントでは、参照ページはAPI Referenceセクションにあります。

補足: 貢献するページによって、異なる声とスタイルに従う必要がある場合があります。例えば、概念的なページはより指導的であり、ユーザーに向けて「あなた」という言葉を使用します。参照ページはよりテクニカルで、「作成する、更新する、受け入れる」などのより命令的な言葉を使用し、「あなた」という言葉を省略する傾向があります。

声

ドキュメント全体で一貫したスタイルと声を維持するためのガイドラインをいくつか紹介します：

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

これらのガイドラインは網羅的ではありませんが、始めるのに役立つはずです。技術文書についてさらに詳しく知りたい場合は、Google Technical Writing Courseをご覧ください。

ドキュメントへの貢献とNext.jsコミュニティへの参加に感謝します！