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

ドキュメント貢献ガイド

Next.js ドキュメント貢献ガイドへようこそ！ここに来てくれてとても嬉しいです。

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

なぜ寄稿するのか？​

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

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

どうやって貢献するのか​

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

GitHub ワークフロー​

GitHub が初めての場合は、リポジトリのフォーク、ブランチの作成、プルリクエストの提出方法を学ぶために、GitHub オープンソースガイドをお勧めします。

Good to know: ドキュメントの基本的なコードは、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 用のIntelliSenseとシンタックスハイライト
  • Prettier: 保存時にMDXファイルを整形

レビュープロセス​

寄稿を提出すると、Next.js または Developer Experience チームが変更内容をレビューし、フィードバックを提供し、準備が整ったらプルリクエストをマージします。

質問がある場合やさらにサポートが必要な場合は、PR のコメントでお知らせください。Next.js ドキュメントに貢献し、コミュニティの一員であることに感謝します！

Tip: 提出前に Prettier を実行するには、pnpm prettier-fix を実行してください。

ファイル構造​

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

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

たとえば、functions API Reference 内のページは、特定の関数を見つけやすくするためにアルファベット順に並んでいます：

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

しかし、routing section では、ファイルに二桁の数字がプレフィックスされており、開発者が学ぶべき順序で並んでいます：

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 イメージに使用されます。
descriptionSEO 用の <meta name="description"> タグに使われるページの説明。
required-fields.mdx
---
title: Page Title
description: Page Description
---

ページタイトルは 2-3 語（例：画像の最適化）、説明は 1-2 文（例：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.
---

このAPIリファレンスは、Linkコンポーネントで使用可能なpropsおよび設定オプションを理解するのに役立ちます。
pages/.../link.mdx
---
title: <Link>
description: API reference for the <Link> component.
source: app/api-reference/components/link
---

{/* このページを編集しないでください。 */}
{/* このページのコンテンツは上記のソースから引き込まれています。 */}

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

共有コンテンツ​

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

コンテンツを正しい router のみ表示するように <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>
}

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

言語とファイル名​

コードブロックには、言語と filename を含むヘッダーが必要です。filename prop を追加して、コマンドの入力場所を示す特別な終端アイコンを表示します。たとえば：

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 prop でリンクしています：

code-example.mdx
```tsx title="app/page.tsx" switcher

```

```jsx title="app/page.js" switcher

```

Good to know: 将来的に TypeScript のスニペットを自動的に JavaScript にコンパイルする予定です。それまでの間、transform.tools を使用できます。

行のハイライト​

コード行をハイライトできます。これにより、コードの特定の部分に注目を集めたいときに便利です。highlight prop に数値を渡すことで行をハイライトできます。

単一行： 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**: これは単一行のノートです。

> **Good to know**:
>
> - 複数行のノートにもこの形式を使用します。
> - 知っておく価値があるか頭に留めておく価値がある事項が複数あることもあります。

出力：

Good to know: これは単一行のノートです。

Good to know:

  • 複数行のノートにもこの形式を使用します。
  • 知っておく価値があるか頭に留めておく価値がある事項が複数あることもあります。

関連リンクは、ユーザーの学習の流れを導き、次のステップへのリンクを追加します。

  • リンクはページのメインコンテンツの下のカードに表示されます。
  • リンクは子ページがあるページに自動生成されます。たとえば、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 ドキュメントでは、概念的なページは Building Your Application セクションにあります。
  • リファレンスページは、特定の API を説明するために使われます。通常、より短く、焦点を絞っています。Next.js ドキュメントでは、リファレンスページは API Reference セクションにあります。

Good to know: 貢献しているページに応じて、別の声やスタイルに従う必要があるかもしれません。たとえば、概念的なページはより説明的であり、ユーザーを指すために「あなた」という言葉を使用します。リファレンスページはより技術的で、「作成、更新、受け入れ」のようなより命令的な言葉を使用し、通常は「あなた」という言葉を省略します。

声​

ドキュメント全体で一貫したスタイルと声を維持するためのガイドラインをいくつか示します：

  • 明確で簡潔な文章を書きましょう。脱線を避けてください。
    • コンマを多用していることに気づいた場合は、文を複数の文に分割するか、リストを使用してください。
    • 複雑な単語をシンプルなものに置き換えましょう。例えば、use の代わりに utilize を使うことなど。
  • 単語このは注意深く使用しましょう。曖昧で混乱を招く可能性があるので、不明確な場合は文の主題を繰り返すことを恐れないでください。
    • 例えば、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 コミュニティの一員であることに感謝します！