logoNext.js 日本語
ドキュメントブログ学習
はじめに/コミュニティ/貢献ガイド

ドキュメント貢献ガイド

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 ファイルに次の行を追加します：

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

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

拡張機能

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

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

レビュープロセス

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

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

ヒント: PR を提出する前に pnpm prettier-fix を実行して Prettier を実行してください。

ファイル構造

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

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

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

03-functions
├── cookies.mdx
├── draft-mode.mdx
├── fetch.mdx
└── ...

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

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

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

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

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

メタデータ

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

必須フィールド

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

フィールド説明
titleページの <h1> タイトル、SEO と OG 画像に使用されます。
descriptionページの説明、SEO のための <meta name="description"> タグに使用されます。
required-fields.mdx
---
title: ページタイトル
description: ページの説明
---

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

オプションフィールド

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

フィールド説明
nav_titleナビゲーションでページのタイトルを上書きします。ページタイトルが長すぎる場合に便利です。指定しない場合、title フィールドが使用されます。
source共有ページにコンテンツを取り込みます。共有ページ を参照してください。
relatedドキュメントの下部に関連ページのリストを追加します。これらは自動的にカードに変換されます。関連リンク を参照してください。
optional-fields.mdx
---
nav_title: ナビゲーション項目タイトル
source: app/building-your-application/optimizing/images
related:
  description: 画像コンポーネント API リファレンスを参照してください。
  links:
    - app/api-reference/components/image
---

App と Pages ドキュメント

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

共有ページ

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

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

この API リファレンスは、Link コンポーネントで利用可能な props
と設定オプションの使用方法を理解するのに役立ちます。
pages/.../link.mdx
---
title: <Link>
description: <Link> コンポーネントの API リファレンス。
source: app/api-reference/components/link
---

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

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

共有コンテンツ

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

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

app/.../link.mdx
このコンテンツは App と Pages で共有されます。

<PagesOnly>

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

</PagesOnly>

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

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

コードブロック

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

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

app/page.tsx
import Link from 'next/link'

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

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

言語とファイル名

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

code-example.mdx
```bash filename="Terminal"
npx create-next-app
```

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

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

言語拡張子
JSX コードを含む JavaScript ファイル```jsx.js
JSX を含まない JavaScript ファイル```js.js
JSX コードを含む TypeScript ファイル```tsx.tsx
JSX を含まない TypeScript ファイル```ts.ts

TS と JS スイッチャー

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

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

code-example.mdx
```tsx filename="app/page.tsx" switcher

```

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

```

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

行のハイライト

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

単一行: highlight={1}

app/page.tsx
import Link from 'next/link'

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

複数行: highlight={1,3}

app/page.tsx
import Link from 'next/link'

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

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

app/page.tsx
import Link from 'next/link'

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

アイコン

以下のアイコンがドキュメントで使用できます：

mdx-icon.mdx
<Check size={18} />
<Cross size={18} />

出力:

Check Icon Cross Icon

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

注記

重要だがクリティカルではない情報には注記を使用します。注記は、メインコンテンツからユーザーを気を散らさずに情報を追加する良い方法です。

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

> **豆知識**:
>
> - 複数行の注記にもこの形式を使用します。
> - 知っておく価値のある複数の項目がある場合もあります。

出力:

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

豆知識:

  • 複数行の注記にもこの形式を使用します。
  • 知っておく価値のある複数の項目がある場合もあります。

関連リンク

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

  • リンクはメインコンテンツの下にカード形式で表示されます。
  • 子ページを持つページには自動的にリンクが生成されます。例えば、最適化 セクションには、すべての子ページへのリンクがあります。

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

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

ネストされたフィールド

フィールド必須？説明
titleオプションカードリストのタイトル。デフォルトは Next Steps です。
descriptionオプションカードリストの説明。
links必須他のドキュメントページへのリンクのリスト。各リスト項目は相対 URL パス（先頭のスラッシュなし）である必要があります。例：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リファレンスセクションにあります。

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

文体

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

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

これらのガイドラインは網羅的ではありませんが、始めるのに役立つはずです。技術文書作成についてさらに深く学びたい場合は、Google Technical Writing Courseをチェックしてください。

ドキュメントへの貢献とNext.jsコミュニティの一員であることに感謝します！

コミュニティ

Next.js コミュニティに参加しましょう