コンテンツへスキップ
はじめにコミュニティ貢献ガイド

ドキュメント貢献ガイド

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のインテリセンスと構文強調表示。
  • Prettier：保存時にMDXファイルをフォーマットします。

レビュープロセス

コントリビューションを提出すると、Next.jsまたはDeveloper Experienceチームが変更内容を確認し、フィードバックを提供し、準備が整い次第プルリクエストをマージします。

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

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

ファイル構造

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

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

たとえば、関数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
└── ...

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

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

マニフェストファイル（ドキュメントナビゲーションを生成する別の一般的な方法）の使用を検討しましたが、マニフェストはファイルとすぐに同期しなくなることがわかりました。ファイルシステムルーティングを使用すると、ドキュメントの構造について強制的に考える必要があり、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文（例：Next.jsでの画像の最適化方法を学ぶ）に制限することをお勧めします。

オプションフィールド

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

フィールド説明
nav_titleナビゲーション内のページのタイトルを上書きします。これは、ページのタイトルが長すぎて収まらない場合に便利です。提供されない場合、titleフィールドが使用されます。
sourceコンテンツを共有ページにプルします。「共有ページ」を参照してください。
relatedドキュメントの下部にある関連ページのリスト。これらは自動的にカードに変換されます。「関連リンク」を参照してください。
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
---

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>コンポーネントには、Pagesでのみ利用可能で、Appでは利用できない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 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} />

出力

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

注記

重要だが必須ではない情報には、注記を使用します。注記は、ユーザーのメインコンテンツへの集中を妨げることなく情報を追加するのに適しています。

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.

出力

知っておくと良いこと：これは単一行の注記です。

知っておくと良いこと:

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

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

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

ページのメタデータの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オプションカードリストのタイトル。デフォルトは次のステップです。
descriptionオプションカードリストの説明。
リンク必須他のドキュメントページへのリンクのリスト。各リスト項目は、相対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ドキュメントでは、概念ページはアプリケーションの構築セクションにあります。
  • リファレンスページは、特定の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 のような単語をよく使う場合は、受動態を使用している可能性があります。
  • easy、quick、simple、just などの単語は使用しないでください。これは主観的であり、ユーザーを落胆させる可能性があります。
  • don't、can't、won't などの否定的な単語は避けてください。これは読者を落胆させる可能性があります。
    • たとえば、"ページ間のリンクを作成するために<a>タグを使用しないでください" の代わりに "ページ間のリンクを作成するには、Link コンポーネントを使用できます" とします。
  • 二人称 (you/your) で記述しましょう。これはより個人的で魅力的です。
  • 性別中立的な言葉を使用しましょう。読者を指す場合は、developers、users、または readers を使用します。
  • コード例を追加する場合は、適切にフォーマットされ、動作することを確認してください。

これらのガイドラインはすべてを網羅しているわけではありませんが、始めるのに役立つはずです。技術文書の作成についてさらに深く知りたい場合は、Google 技術文書コース をご確認ください。

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