コンテンツにスキップ
Next.js Docsコミュニティコントリビューションガイド

Docsコントリビューションガイド

Next.js Docsコントリビューションガイドへようこそ！皆様のご参加を歓迎いたします。

このページでは、Next.jsのドキュメントを編集する方法についての説明を提供します。私たちの目標は、コミュニティの誰もがドキュメントの改善に貢献できると実感できることです。

なぜ貢献するのか？

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

Next.jsのドキュメントに貢献することで、すべての開発者にとってより堅牢な学習リソースを構築するのに役立ちます。タイプミス、分かりにくいセクションを見つけた場合でも、特定のトピックが不足していることに気づいた場合でも、あなたの貢献は歓迎され、感謝されます。

貢献方法

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

GitHubワークフロー

GitHubが初めての方は、リポジトリのフォーク、ブランチの作成、プルリクエストの送信方法を学ぶために、GitHub Open Source Guideを読むことをお勧めします。

知っておくと良いこと：ドキュメントの基盤となるコードはプライベートなコードベースにあり、Next.jsの公開リポジトリに同期されています。これは、ドキュメントをローカルでプレビューできないことを意味します。ただし、プルリクエストをマージすると、nextjs.orgで変更を確認できます。

MDXの書き方

ドキュメントはMDXで記述されています。これは、JSX構文をサポートするマークダウン形式です。これにより、ドキュメントにReactコンポーネントを埋め込むことができます。GitHub Markdownガイドでマークダウン構文の概要を確認してください。

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内の各フォルダとファイル/docsはルートセグメントを表します。これらのセグメントは、URLパス、ナビゲーション、パンくずリストの生成に使用されます。

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

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

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

しかし、Routingセクションでは、開発者がこれらの概念を学ぶべき順序で、ファイルに2桁の数値がプレフィックスとして付けられています。

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

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

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

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

Metadata

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

必須フィールド

以下のフィールドは必須です。

フィールド説明
titleページの<h1>タイトル。SEOとOG画像に使用されます。
descriptionページの<meta name="description">タグに使用される説明。SEO用です。
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コンテンツを共有ページに読み込みます。共有ページを参照してください。
relatedドキュメントの下部にある関連ページの一覧です。これらは自動的にカードに変換されます。関連リンクを参照してください。
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>コンポーネントには、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

知っておくと良いこと:

  • JSXコードを含むJavaScriptファイルには、.js拡張子を使用してください。
  • たとえば、 ```jsx filename="app/layout.js"

TSと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
> **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オプションカードリストのタイトル。デフォルトは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ページには、ページの上部にジャンプ先セクションリンク（可能な場合）を含む概要テーブルが必要です。
  • 次のステップ（関連リンク）：ユーザーの学習ジャーニーをガイドするために、関連ページへのリンクを追加します。

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

ページの種類

ドキュメントページは、Conceptual（概念）とReference（リファレンス）の2つのカテゴリにも分類されます。

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

知っておくと良いこと：貢献するページによっては、異なる声とスタイルに従う必要がある場合があります。たとえば、概念ページはより指示的で、ユーザーに話しかけるときにyouという言葉を使用します。リファレンスページはより技術的で、"create, update, accept"のような命令的な言葉を多く使用し、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"（ページ間のリンクを作成するために<a>タグを使用しないでください）ではなく、"You can use the Link component to create links between pages"（Linkコンポーネントを使用してページ間のリンクを作成できます）。
  • 二人称（you/your）で記述してください。より個人的で魅力的になります。
  • 性別ニュートラルな言葉を使用してください。オーディエンスを参照する場合、developers,users,またはreadersを使用します。
  • コード例を追加する場合は、適切にフォーマットされ、動作することを確認してください。

これらのガイドラインは網羅的ではありませんが、開始の助けになるはずです。テクニカルライティングについてさらに深く知りたい場合は、Google Technical Writing Courseを確認してください。

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