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

ドキュメント貢献ガイド

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チームが変更を確認し、フィードバックを提供し、準備が整い次第プルリクエストをマージします。

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

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

ファイル構造

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

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

例えば、関数APIリファレンスでは、開発者が特定の関数を見つけやすくするために、ページがアルファベット順にソートされています。

04-functions
├── after.mdx
├── cacheLife.mdx
├── cacheTag.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ページの<meta name="description">タグに使用される説明文。SEOに利用されます。
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.
---
 
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. */}

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

共有コンテンツ

共有ページでは、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

知っておくと良いこと:

  • JavaScriptファイルでは、JSXコードを含む場合でもjs拡張子を使用してください。
  • 例： ```jsx filename="app/layout.js"

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任意カードリストの説明。
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ページには、ページ冒頭にジャンプリンク付きの概要テーブル（可能な場合）を配置する必要があります。
  • 次のステップ（関連リンク）: ユーザーの学習を導くために、関連ページへのリンクを追加します。

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

ページの種類

ドキュメントページは、「概念ページ」と「リファレンスページ」の2つのカテゴリに分けられます。

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

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

トーン

ドキュメント全体で一貫したスタイルとトーンを維持するためのガイドラインを以下に示します。

  • 明確で簡潔な文を記述します。本筋から逸脱しないようにしてください。
    • 多くのカンマを使用している場合は、文を複数の文に分割するか、箇条書きを使用することを検討してください。
    • 複雑な言葉をより簡単なものに置き換えます。例えば、utilizeの代わりにuseを使用します。
  • 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などの否定的な単語の使用は避けてください。これは読者を落胆させる可能性があります。
    • 例: "Don't use the <a> tag to create links between pages" の代わりに "You can use the Link component to create links between pages"。
  • 二人称（あなた/あなたの）で記述します。これはより個人的で引き込まれます。
  • 性差のない言葉を使用します。読者層に言及する場合は、開発者、ユーザー、または読者を使用してください。
  • コード例を追加する場合は、適切にフォーマットされ、動作することを確認してください。

これらのガイドラインは網羅的ではありませんが、始めるのに役立つでしょう。テクニカルライティングをさらに深く学びたい場合は、Googleテクニカルライティングコースを参照してください。

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