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

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

マニフェストファイル（ドキュメントナビゲーションを生成するもう1つの一般的な方法）の使用を検討しましたが、マニフェストはファイルとすぐに同期が取れなくなることがわかりました。ファイルシステムルーティングは、ドキュメントの構造について考えることを強制し、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 プロップを追加すると、ユーザーがコマンドを入力する場所を案内する特別なターミナルアイコンがレンダリングされます。例：

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 プロップでリンクしています：

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

```

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

```

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

行のハイライト

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

単一行: 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 ページには、可能な場合はセクションへのジャンプリンクを含む概要テーブルが必要です。
  • 次のステップ（関連リンク）: ユーザーの学習の旅を導くために、関連ページへのリンクを追加します。

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

ページの種類

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

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

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

文体

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

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

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

ドキュメントへの貢献とNext.jsコミュニティの一員となっていただきありがとうございます！

コミュニティ

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