メインコンテンツまでスキップ

ドキュメント貢献ガイド

Next.js Docs Contribution Guideへようこそ！ここに来てくれてうれしいです。

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

なぜ貢献するのか？​

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

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

貢献方法​

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

GitHubのワークフロー​

GitHubに馴染みがない場合は、GitHub Open Source Guideを読んで、リポジトリをフォークし、ブランチを作成し、プルリクエストを送信する方法を学ぶことをお勧めします。

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

MDXを書く​

ドキュメントはMDXで書かれています。これはJSX構文をサポートするマークダウン形式です。これにより、Reactコンポーネントをドキュメントに埋め込むことができます。マークダウン構文の簡単な概要については、GitHub Markdown Guideをご覧ください。

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のドキュメントに貢献し、私たちのコミュニティの一員になってくれてありがとう！

Tip: プルリクエストを提出する前に、pnpm prettier-fixを実行してPrettierを実行することをお勧めします。

ファイル構造​

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

ファイル構造は、サイト上で見えるナビゲーションを反映しており、デフォルトではナビゲーションアイテムはアルファベット順にソートされています。ただし、フォルダやファイル名の前に2桁の数字（00-）を追加することで、アイテムの順序を変更できます。

例えば、functions API Referenceでは、ページがアルファベット順に並べられており、開発者が特定の関数を見つけやすくしています：

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

Why not use a manifest?

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

メタデータ​

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

必須フィールド​

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

フィールド説明
titleページの<h1>タイトル、SEOとOG画像に使用されます。
description<meta name="description">タグで使用されるページの説明。
required-fields.mdx
---
title: 'Page Title'
description: 'Page Description'
---

ページタイトルを2-3語に限定（例：Optimizing Images）し、説明を1-2文に限定（例：Next.jsでの画像の最適化方法について学びましょう）することが良い習慣です。

任意フィールド​

次のフィールドは任意です：

フィールド説明
nav_titleナビゲーションでページのタイトルを上書きします。ページのタイトルが長すぎて収まりきれない場合に便利です。指定されていない場合は、titleフィールドが使用されます。
source共有ページにコンテンツを引き込みます。詳しくはShared Pagesを参照してください。
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フィールドを使用して、1つのページから別のページにコンテンツを引き込みます。例えば、<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でのみ使用可能なshallowプロップがありますが、Appにはありません。

コンテンツを正しいルーターにのみ表示するために、コンテンツブロックを<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プロップを追加します。例えば：

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の例を続けて書き、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

ダイアグラム​

ダイアグラムは、複雑な概念を説明するための素晴らしい方法です。私たちは、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のドキュメントでは、アプリケーションの構築セクションに概念的ページが含まれています
  • リファレンスページは、特定のAPIについて説明するために使用されます。通常、より短く、より焦点を絞っています。Next.jsのドキュメントでは、APIリファレンスセクションにリファレンスページが含まれています

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> タグを使用しないでください」といったように
  • 2人称（あなた/あなたの）で書きます。これはより個人的で魅力的です
  • ジェンダーニュートラルな言語を使用します。読者に言及する際には開発者やユーザー、読者といった言葉を使用します
  • コード例を追加する場合は、適切にフォーマットされており、動作していることを確認します

これらのガイドラインは網羅的ではありませんが、開始する際の役立てにしてください。技術文書についてさらに深く学びたい場合は、Google Technical Writing Courseをご覧ください。

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