Docs Contribution Guide

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

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

なぜ貢献するのか？

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

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

どのように貢献するか

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

GitHubワークフロー

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

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

MDXの書き方

ドキュメントは、JSX構文をサポートするマークダウン形式のMDXで書かれています。これにより、ドキュメントに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語（例：Optimizing Images）に、説明は1〜2文（例：Learn how to optimize images in Next.js）に制限するのが良いプラクティスです。

オプションフィールド

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

フィールド	説明
`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.
---

This API reference will help you understand how to use the props
and configuration options available for the Link Component.

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

{/* DO NOT EDIT THIS PAGE. */}
{/* The content of this page is pulled from the source above. */}

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

共有コンテンツ

共有ページでは、App RouterまたはPages Routerに特有のコンテンツがある場合があります。たとえば、<Link>コンポーネントには、AppではなくPagesでのみ利用可能なshallowプロップがあります。

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

app/.../link.mdx
This content is shared between App and Pages.

<PagesOnly>

This content will only be shown on the Pages docs.

</PagesOnly>

This content is shared between App and 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 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

TSとJSのスイッチャー

TypeScriptとJavaScriptを切り替えるための言語スイッチャーを追加します。コードブロックは、ユーザーに対応するために、まずTypeScriptで記述し、JavaScriptバージョンを提供します。

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

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プロップに番号を渡すことで行をハイライトできます。

単一行: 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**: This is a single line note.

> **Good to know**:
>
> - We also use this format for multi-line notes.
> - There are sometimes multiple items worth knowing or keeping in mind.

出力:

Good to know: This is a single line note.

Good to know:

We also use this format for multi-line notes.

There are sometimes multiple items worth knowing or keeping in mind.

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

リンクは、ページのメインコンテンツの下にカードで表示されます。
リンクは、子ページを持つページに対して自動的に生成されます。たとえば、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`

図解

図解は、複雑な概念を説明するのに最適な方法です。私たちは、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セクションにあります。

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​

スタイルガイド​

ページテンプレート​

ページタイプ​

声​