Menu

Next.js ドキュメント貢献ガイド

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

このページでは、Next.jsドキュメントを編集する方法を説明します。私たちのゴールは、コミュニティのすべての人が貢献し、ドキュメントを改善できるようにすることです。

なぜ貢献するのか？

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

Next.jsのドキュメントに貢献することで、すべての開発者のための堅牢な学習リソースの構築を支援できます。誤字を見つけた、わかりにくいセクションがある、または特定のトピックが欠けていることに気づいた場合、あなたの貢献を歓迎し、感謝します。

貢献方法

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

GitHubワークフロー

GitHubを初めて使用する場合は、リポジトリをフォーク、ブランチの作成、プルリクエストの送信方法について、GitHubオープンソースガイドを読むことをお勧めします。

補足: 基礎となるドキュメントのコードは、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のインテリセンスと構文ハイライト
  • Prettier：保存時にMDXファイルをフォーマット

レビュープロセス

貢献を送信すると、Next.jsまたはDeveloper Experienceチームが変更内容を確認し、フィードバックを提供し、準備ができたらプルリクエストをマージします。

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

ヒント: プルリクエストを送信する前に、pnpm prettier-fixを実行してPrettierを実行してください。

ファイル構造

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

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

例えば、関数APIリファレンスでは、ページは開発者が特定の関数を見つけやすいようにアルファベット順に並べられています：

04-functions
├── cacheTag.mdx
├── connection.mdx
├── cookies.mdx
└── ...

一方、ルーティングセクションでは、ファイルには2桁の数字が接頭辞として付けられ、開発者が概念を学ぶ順序で並べられています：

01-routing
├── 01-defining-routes.mdx
├── 02-pages.mdx
├── 03-layouts-and-templates.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フィールドを使用して、あるページから別のページにコンテンツを取り込みます。例えば、<Link>コンポーネントはAppとPagesで_ほぼ_同じように動作します。コンテンツを重複させる代わりに、app/.../link.mdxからpages/.../link.mdxにコンテンツを取り込むことができます：

app/.../link.mdx
---
title: <Link>
description: LinkコンポーネントのAPIリファレンス
---
 
このAPIリファレンスは、Linkコンポーネントで利用可能なプロップと
設定オプションの使用方法を理解するのに役立ちます。
pages/.../link.mdx
---
title: <Link>
description: LinkコンポーネントのAPIリファレンス
source: app/api-reference/components/link
---
 
{/* このページは編集しないでください。 */}
{/* このページのコンテンツは上記のソースから取り込まれます。 */}

私たちはそのため、一箇所でコンテンツを編集し、両セクションに反映させることができます。

共有コンテンツ

共有ページでは、App Router または Pages Router に固有のコンテンツが存在することがあります。例えば、<Link> コンポーネントには Pages でのみ利用可能な shallow プロップがありますが、App では利用できません。

コンテンツが正しいルーターでのみ表示されるようにするために、<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>
}

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

言語とファイル名

コードブロックには、言語とファイル名を含むヘッダーが必要です。コマンドを入力する場所をユーザーに示すために、特別なTerminalアイコンをレンダリングするには、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 and JS スイッチャー

TypeScriptとJavaScriptを切り替えるための言語スイッチャーを追加します。コードブロックは、Javascriptバージョンを持つTypeScriptファイルを最初に記述し、ユーザーに対応するようにします。

現在は、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
> **補足**: これは単一行の注意事項です。
 
> **補足**:
>
> - 複数行の注意事項にもこの形式を使用します。
> - 時には、知っておくべきまたは念頭に置くべき複数の項目があります。

出力:

補足: これは単一行の注意事項です。

補足:

  • 複数行の注意事項にもこの形式を使用します。
  • 時には、知っておくべきまたは念頭に置くべき複数の項目があります。

関連リンク

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

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

ページのメタデータにある 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）である必要があります。

ダイアグラム

ダイアグラムは複雑な概念を説明するための素晴らしい方法です。Verceiのデザインガイドに従い、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リファレンスセクションにあります。

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

口調

ドキュメント全体で一貫したスタイルと口調を維持するためのガイドラインは以下の通りです：

  • 明確で簡潔な文を書きます。脱線を避けます。
    • カンマを多用している場合は、文を複数の文に分割するか、リストを使用することを検討してください。
    • 複雑な言葉をより簡単な言葉に置き換えます。例えば、_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_などのネガティブな言葉を避けます。これは読者を落胆させる可能性があります。
    • 例えば、"Don't use the <a> tag to create links between pages"ではなく、"You can use the Link component to create links between pages"。
  • 二人称（you/your）で書きます。これはより個人的で魅力的です。
  • 性中立的な言語を使用します。オーディエンスを指す際は、developers、users、または_readers_を使用します。
  • コード例を追加する場合は、適切にフォーマットされ、動作することを確認します。

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

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