Docs Contribution Guide

Next.jsドキュメント貢献ガイドへようこそ！ここに来ていただき嬉しいです。

このページでは、Next.jsのドキュメントを編集する方法についての指示を提供します。私たちの目標は、コミュニティのすべての人がドキュメントに貢献し、改善する力を感じられるようにすることです。

なぜ貢献するのか？

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

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

どのように貢献するか

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

GitHubワークフロー

GitHubに不慣れな場合は、GitHubオープンソースガイドを読んで、リポジトリをフォークし、ブランチを作成し、プルリクエストを送信する方法を学ぶことをお勧めします。

Good to know: 基本的なドキュメントコードはプライベートなコードベースにあり、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のIntellisenseと構文ハイライト
Prettier: 保存時にMDXファイルをフォーマット

レビュープロセス

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

プルリクエストのコメントで質問がある場合や、さらなる支援が必要な場合はお知らせください。Next.jsのドキュメントに貢献し、私たちのコミュニティの一員であることに感謝します！

Tip: プルリクエストを提出する前にpnpm prettier-fixを実行してPrettierを実行してください。

ファイル構造

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

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

たとえば、functions API Referenceでは、ページは特定の関数を見つけやすくするためにアルファベット順にソートされています：

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

しかし、routing sectionでは、ファイルは2桁の数字でプレフィックスされ、開発者がこれらの概念を学ぶべき順序でソートされています：

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

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

Why not use a manifest?

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

メタデータ

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

必須フィールド

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

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

required-fields.mdx
---
title: Page Title
description: Page Description
---

ページタイトルは2〜3語に、説明は1〜2文に制限するのが良いプラクティスです（例：画像の最適化を学ぶ）。

オプションフィールド

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

フィールド	説明
`nav_title`	ナビゲーションでページのタイトルを上書きします。ページのタイトルが長すぎて収まらない場合に便利です。指定されていない場合、`title`フィールドが使用されます。
`source`	共有ページにコンテンツを引き込みます。Shared Pagesを参照してください。
`related`	ドキュメントの下部に関連ページのリストを表示します。これらは自動的にカードに変換されます。Related Linksを参照してください。
`version`	開発の段階。例：`experimental`、`legacy`、`unstable`、`RC`

optional-fields.mdx
---
nav_title: Nav Item Title
source: app/building-your-application/optimizing/images
related:
  description: See the image component API reference.
  links:
    - app/api-reference/components/image
version: experimental
---

`App`と`Pages`のドキュメント

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

共有ページ

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

app/.../link.mdx
---
title: <Link>
description: API reference for the <Link> component.
---

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

pages/.../link.mdx
---
title: <Link>
description: API reference for the <Link> component.
source: app/api-reference/components/link
---

{/* このページを編集しないでください。 */}
{/* このページの内容は上記のソースから引き込まれています。 */}

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

共有コンテンツ

共有ページでは、App RouterまたはPages Routerに特有のコンテンツがある場合があります。たとえば、<Link>コンポーネントにはAppではなくPagesでのみ利用可能な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 title="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

Good to know:

JavaScriptファイルでJSXコードを使用する場合は、**js**拡張子を使用してください。

たとえば、```jsx title="app/layout.js"

TSとJSのスイッチャー

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

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

code-example.mdx
<Tabs>
<TabItem value="tsx" label="TypeScript">

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

```

</TabItem>
<TabItem value="jsx" label="JavaScript">

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

```

</TabItem>
</Tabs>

Good to know: 将来的には、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} />

出力:

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

ノート

重要ではあるが重要ではない情報にはノートを使用します。ノートは、ユーザーをメインコンテンツから逸らさずに情報を追加する良い方法です。

notes.mdx
> **Good to know**: これは単一行のノートです。

> **Good to know**:
>
> - 複数行のノートにもこの形式を使用します。
> - 知っておくべきことや心に留めておくべきことが複数ある場合があります。

出力:

Good to know: これは単一行のノートです。

Good to know:

複数行のノートにもこの形式を使用します。

知っておくべきことや心に留めておくべきことが複数ある場合があります。

関連リンクは、ユーザーの学習の旅をガイドし、論理的な次のステップへのリンクを追加します。

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

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

example.mdx
---
related:
  description: Learn how to quickly get started with your first application.
  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 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セクションにあります。

Good to know: 貢献するページによっては、異なる声とスタイルに従う必要があるかもしれません。たとえば、概念的なページはより指導的で、ユーザーに対してあなたという言葉を使用します。リファレンスページはより技術的で、「作成、更新、受け入れ」などの命令的な言葉を使用し、あなたという言葉を省略する傾向があります。

声

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

明確で簡潔な文を書く。脱線を避ける。
- たくさんのコンマを使用している場合は、文を複数の文に分けるか、リストを使用することを検討してください。
- 複雑な言葉をより簡単な言葉に置き換える。たとえば、useの代わりにutilize。
thisという言葉に注意を払う。それは曖昧で混乱を招く可能性があるため、文の主題が不明な場合は繰り返すことを恐れないでください。
- たとえば、Next.js uses Reactの代わりにNext.js uses this。
受動態ではなく能動態を使用する。能動態の文は読みやすいです。
- たとえば、Next.js uses Reactの代わりにReact is used by Next.js。wasやbyのような言葉を使用している場合、受動態を使用している可能性があります。
easy、quick、simple、justなどの言葉を避ける。これは主観的であり、ユーザーを落胆させる可能性があります。
don't、can't、won'tなどの否定的な言葉を避ける。これは読者を落胆させる可能性があります。
- たとえば、「ページ間のリンクを作成するにはLinkコンポーネントを使用できます」の代わりに「ページ間のリンクを作成するために<a>タグを使用しないでください」。
二人称（あなた/あなたの）で書く。これはより個人的で魅力的です。
ジェンダーニュートラルな言語を使用する。オーディエンスを指すときは、開発者、ユーザー、または読者を使用します。
コード例を追加する場合は、適切にフォーマットされ、動作していることを確認してください。

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

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

なぜ貢献するのか？​

どのように貢献するか​

GitHubワークフロー​

MDXの書き方​

VSCode​

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

拡張機能​

レビュープロセス​

ファイル構造​

メタデータ​

必須フィールド​

オプションフィールド​

AppとPagesのドキュメント​

共有ページ​

共有コンテンツ​

コードブロック​

言語とファイル名​

TSとJSのスイッチャー​

行のハイライト​

アイコン​

ノート​

関連リンク​

ネストされたフィールド​

ダイアグラム​

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

スタイルガイド​

ページテンプレート​

ページタイプ​

声​