Menu

ドキュメント貢献ガイド

Next.jsドキュメント貢献ガイドへようこそ。皆さんのご参加をお待ちしています。

このページでは、Next.jsドキュメントを編集する方法について説明します。私たちの目標は、コミュニティの全員がドキュメントへの貢献と改善を行うための力を得られることです。

なぜ貢献するのか？

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

Next.jsドキュメントに貢献することで、全ての開発者にとって、より堅牢な学習リソースの構築をお手伝いいただけます。タイプミスを見つけた場合、混乱を招くセクションを発見した場合、または特定のトピックが不足していることに気づいた場合、皆さんの貢献は大歓迎です。

貢献する方法

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

GitHubワークフロー

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

補足：ドキュメントの基礎となるコードはプライベートコードベースに存在し、Next.jsパブリックリポジトリと同期されています。つまり、ドキュメントをローカルでプレビューすることはできません。ただし、プルリクエストがマージされた後は、nextjs.orgで変更内容を確認できます。

MDXの執筆

ドキュメントはMDXで作成されており、これはJSX構文をサポートするMarkdown形式です。これにより、ドキュメントにReactコンポーネントを埋め込むことができます。Markdown構文の概要については、GitHub Markdownガイドを参照してください。

VSCode

ローカルで変更内容をプレビューする

VScodeには、編集内容をローカルで確認するために使用できる組み込みMarkdownプレビューアがあります。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ドキュメントへの貢献と、コミュニティの一部になっていただきありがとうございます。

ヒント：プルリクエストを送信する前に、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ページの説明。SEO用の<meta name="description">タグに使用されます。
required-fields.mdx
---
title: ページタイトル
description: ページの説明
---

ページタイトルを2～3語（例：画像の最適化）に、説明を1～2文（例：Next.jsで画像を最適化する方法を学びます）に制限することをお勧めします。

オプションフィールド

以下のフィールドはオプションです。

フィールド説明
nav_titleナビゲーション内のページのタイトルをオーバーライドします。ページのタイトルが長すぎる場合に便利です。指定されていない場合、titleフィールドが使用されます。
sourceコンテンツを共有ページにプルします。共有ページを参照してください。
relatedドキュメントの下部に関連ページのリスト。これらは自動的にカードに変換されます。関連リンクを参照してください。
version開発段階。例：experimental、legacy、unstable、RC
optional-fields.mdx
---
nav_title: ナビゲーション項目タイトル
source: /docs/app/building-your-application/optimizing/images
related:
  description: 画像コンポーネントAPIリファレンスを参照してください。
  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: <Link>コンポーネントのAPIリファレンス。
---
 
このAPIリファレンスは、Linkコンポーネントで利用可能なプロパティと設定オプションの使用方法を理解するのに役立ちます。
pages/.../link.mdx
---
title: <Link>
description: <Link>コンポーネントのAPIリファレンス。
source: /docs/app/api-reference/components/link
---
 
{/* このページを編集しないでください。 */}
{/* このページのコンテンツは上記のソースからプルされています。 */}

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

共有コンテンツ

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

コンテンツが正しいルーターでのみ表示されるようにするために、コンテンツブロックを<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プロップを追加して、特別なTerminalアイコンをレンダリングすると、ユーザーがコマンドを入力する場所を理解するのに役立ちます。例えば。

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"

TypeScriptとJavaScriptスイッチャー

TypeScriptとJavaScriptを切り替えるための言語スイッチャーを追加します。コードブロックはTypeScriptを優先とし、ユーザーに対応するJavaScriptバージョンを備える必要があります。

現在、TypeScriptとJavaScriptの例を1つ後に1つ記述し、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
> **補足**：これは1行の注釈です。
 
> **補足**：
>
> - 複数行の注釈にもこの形式を使用します。
> - 知る価値のある、または覚えておく価値のある項目が複数ある場合もあります。

出力：

補足：これは1行の注釈です。

補足：

  • 複数行の注釈にもこの形式を使用します。
  • 知る価値のある、または覚えておく価値のある項目が複数ある場合もあります。

関連リンク

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

  • リンクは、ページのメインコンテンツの下にカードで表示されます。
  • リンクは、子ページを持つページに対して自動的に生成されます。

ページのメタデータの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オプションカードリストのタイトル。デフォルトは次のステップです。
descriptionオプションカードリストの説明。
links必須他のドキュメントページへのリンクのリスト。各リストアイテムは、相対URLパス（先頭のスラッシュなし）である必要があります。例：app/api-reference/file-conventions/page

図

図は複雑な概念を説明するための優れた方法です。Figmaを使用して図を作成し、Vercelのデザインガイドに従っています。

図は現在、プライベートNext.jsサイトの/publicフォルダに存在します。図を更新または追加したい場合は、GitHubイシューをアイデアと共に開いてください。

カスタムコンポーネントとHTML

以下は、ドキュメント用に使用可能なReactコンポーネントです。<Image />（next/image）、<PagesOnly />、<AppOnly />、<Cross />、<Check />です。<details>タグ以外のrawHTMLをドキュメントで許可していません。

新しいコンポーネントのアイデアがある場合は、GitHubイシューを開いてください。

スタイルガイド

このセクションでは、技術ライティングが初めての人のためにドキュメント執筆ガイドラインを含しています。

ページテンプレート

ページの厳密なテンプレートはありませんが、ドキュメント全体で繰り返し表示されるページセクションがあります。

  • **概要：**ページの最初の段落は、機能が何であるか、何に使用されるかをユーザーに伝える必要があります。その後に、最小限の動作例またはそのAPIリファレンスが続きます。
  • **慣例：**機能に慣例がある場合、ここで説明する必要があります。
  • 例：さまざまなユースケースで機能がどのように使用できるかを示します。
  • APIテーブル：APIページのページの上部に、セクションへのジャンプリンク付きの概要テーブルが必要です（可能な場合）。
  • 次のステップ（関連リンク）：ユーザーの学習経路をガイドするために関連ページへのリンクを追加します。

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

ページタイプ

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

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

補足：貢献しているページによっては、異なる音声やスタイルに従う必要がある場合があります。例えば、概念ページはより指示的であり、単語「あなた」を使用してユーザーに対処します。リファレンスページはより技術的であり、「作成」、「更新」、「承認」などのより命令的な単語を使用し、単語「あなた」を省略する傾向があります。

音声

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

  • 明確で簡潔な文を書きます。接線を避けます。
    • 多くの記号を使用していることに気づいた場合は、文を複数の文に分割するか、リストを使用することを検討します。
    • 複雑な単語をより単純な単語に置き換えます。例えば、「活用する」ではなく「使用」。
  • 「これ」という単語に注意してください。あいまいで混乱する可能性があるため、明確でない場合は、文の主語を繰り返すことを恐れないでください。
    • 例えば、「Next.jsはReactを使用しています」は「Next.jsはこれを使用しています」の代わりに。
  • 受動態ではなく能動態を使用します。能動的な文は読みやすいです。
    • 例えば、「React is used by Next.js」ではなく、「Next.js uses React」。「was」や「by」などの単語を使用していることに気づいた場合、受動態を使用している可能性があります。
  • 「簡単」、「迅速」、「シンプル」、「ちょうど」などの単語を避けます。これは主観的であり、ユーザーを落胆させることができます。
  • 「しないでください」、「できません」、「しません」などの否定的な単語を避けます。これは読者を落胆させる可能性があります。
    • 例えば、「ページ間でリンクを作成するために<a>タグを使用しないでください」の代わりに、「Linkコンポーネントを使用してページ間にリンクを作成できます」。
  • 二人称（あなた/あなたの）で書きます。これはより個人的で魅力的です。
  • 性別に中立な言語を使用します。対象ユーザーを指す場合は、「開発者」、「ユーザー」、「リーダー」を使用します。
  • コード例を追加する場合は、適切にフォーマットされ、動作していることを確認してください。

これらのガイドラインは網羅的ではありませんが、開始するのに役立つはずです。技術ライティングについてさらに深く掘り下げたい場合は、Googleテクニカルライティングコースをご確認ください。

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