Lang x Lang

︙

Docs Contribution Guide

Next.js ドキュメンテーション貢献ガイドへようこそ！あなたがここにいることにとても興奮しています。

このページでは、Next.js ドキュメンテーションの編集方法について説明しています。私たちの目標は、コミュニティ内の全員が貢献し、私たちのドキュメントを改良することを自信を持って取り組むことができるようにすることです。

Why Contribute?

オープンソースの仕事は never 終わらず、ドキュメンテーションもそうです。ドキュメンテーションに貢献することは、初心者がオープンソースに参加する良い方法であり、経験豊富な開発者がより複雑なトピックを明確にしながらコミュニティと知識を共有する方法でもあります。

Next.js のドキュメントに貢献することで、皆の開発者にとってより頑健な学習リソースを build するのに私たちを助けています。タイポを見つけたり、混乱するセクションを発見したり、特定のトピックが missing だと気づいたりした場合でも、あなたの貢献は歓迎され、高く評価されます。

How to Contribute

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

GitHub ワークフロー

もし GitHub を初めて使用するのであれば、リポジトリをフォークし、ブランチを作成し、プル request を送信する方法を学ぶために、GitHub Open Source ガイド を読むことをお勧めします。

Good to know: 基礎となるドキュメントの code はプライベートコードベースにあり、 Next.js public リポジトリと同期されています。これは、ローカルでドキュメントを preview できないことを意味します。しかし、プル request をマージした後にnextjs.org で変更を確認することができます。

MDX の記述

ドキュメントは、JSX の syntax をサポートしたマークダウン形式のMDX で書かれています。それにより、React の Component をドキュメントに組み込むことが可能になります。マークダウンの syntax の簡単な概観は、GitHub Markdown ガイド をご覧ください。

VSCode

ローカルでの変更のプレビュー

VSCode には組み込みのマークダウンプレビューアがあり、ローカルで編集内容を確認することができます。MDX ファイル用のプレビューアを有効にするには、ユーザーの settings に設定オプションを追加する必要があります。

コマンドパレットを開きます(⌘ + ⇧ + P on Mac または Ctrl + Shift + P on Windows)、そしてPreferences: Open User Settings (JSON)から検索します。

次に、以下の行をあなたのsettings.jsonファイルに追加してください：

settings.json
{
  "files.associations": {
    "*.mdx": "markdown"
  }
}

次に、コマンドパレットを再度開き、Markdown: Preview FileまたはMarkdown: Open Preview to the Sideを検索します。これにより、書式を変更した内容を確認できる preview window が開きます。

Extensions

また、VSCode ユーザーには次の拡張機能もおすすめします：

  • MDX : MDX のための Intellisense と syntax ハイライト表示。
  • Grammarly ：文法とスペルチェッカー。
  • Prettier : 保存時に MDX ファイルをフォーマットします。

レビュープロセス

あなたが投稿を提出したら、Next.js チームまたは開発者エクスペリエンスチームがあなたの変更をレビューし、フィードバックを提供し、request のプルが準備できたらマージします。

PR のコメントで何か質問があるか、またはさらなる支援が必要な場合は、お知らせください。Next.js ドキュメントへの貢献と、私たちのコミュニティの一部であることに感謝します！

ヒント： PR を提出する前に、pnpm prettier-fixを実行して、Prettier を実行します。

File Structure

ドキュメントはfile-system routingを使用しています。/docs 内の各フォルダとファイルは route セグメントを表しています。これらのセグメントは、URL paths、ナビゲーション、パン粉状態を生成するために使用されます。

ファイル構造はサイト上で見るナビゲーションを反映し、default でナビゲーション項目はアルファベット順に並べられます。しかし、フォルダやファイル名に二桁の number (00-)を前に付けることで、項目の順序を変更することができます。

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

03-functions
├── cookies.mdx
├── draft-mode.mdx
├── fetch.mdx
└── ...

しかし、routing sectionにおいて、ファイルは二桁の number で接頭辞が付けられ、開発者がこれらの概念を学ぶべき順序でソートされます：

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

ページを素早く見つけるために、⌘ + P(Mac)またはCtrl + P(Windows)を使って VSCode の検索バーを開くことができます。そして、探しているページの slug を type します。例えば、defining-routes。

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

マニフェストファイルを使用することも検討しました(ドキュメントのナビゲーションを生成するための別の人気の方法ですが)、しかし、マニフェストはすぐにファイルとの同期を失うことがわかりました。ファイルシステムルーティングは、ドキュメントの構造について考えるように我々を強制し、Next.js によりネイティブの感覚があります。

Metadata

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

必須フィールド

以下のフィールドはrequiredです：

フィールドDescription
titleページの<h1>タイトルで、 SEO や OG 画像の設定に使用されます。
descriptionこのページの description は、 SEO のための<meta name="description">タグで使用されます。
required-fields.mdx
---
title: Page Title
description: Page Description
---

ページタイトルは 2-3 語(例：画像の最適化)に制限するのが良い習慣であり、 description は 1-2 文(例： Next.js で画像の最適化方法を学びましょう)に制限します。

任意のフィールド

次のフィールドはoptionalです：

フィールドDescription
nav_titleナビゲーション内におけるページのタイトルを上書きします。これは、ページのタイトルが長すぎて収まらない場合に便利です。指定しない場合、titleフィールドが使用されます。
source共有ページにコンテンツを引き込みます。共有ページ を参照してください。
relateddocument の下部にある関連ページのリスト。これらは自動的にカードに変換されます。関連リンクを参照してください。
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
---

App and Pages Docs

App Router と Pages Router の機能のほとんどが完全に異なるため、それぞれのドキュメントは別々のセクション(02-app および 03-pages)に保管されています。ただし、両者間で共有されるいくつかの機能もあります。

共有ページ

コンテンツの重複と同期が取れなくなるリスクを避けるために、sourceフィールドを使用して、あるページから別のページにコンテンツを引くようにしています。たとえば、<Link> component は、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> component には、 Pagesでは利用可能だが、Appでは利用できないshallowプロッパティがあります。

コンテンツが正しい router でのみ表示されるようにするために、コンテンツブロックを <AppOnly> または <PagesOnly> Component で囲むことができます：

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.

これらの Component は例や code ブロックで頻繁に使用する可能性があります。

Code Blocks

Code ブロックは、コピー＆ペースト可能な最小限の動作例を含むべきです。つまり、code は追加の設定なしで実行できることを意味します。

例えば、<Link> component の使い方を示している場合、import文と<Link> component 自体を含めるべきです。

app/page.tsx
import Link from 'next/link'

export default function Page() {
  return <Link href="/about">About</Link>
}

常にローカルで例を実行してからそれらをコミットしてください。これにより、code が最新で機能していることを確認することができます。

言語とファイル名

Code ブロックは、言語と filename を含む header を持つべきです。特別な Terminal icon を render するために filename prop を加えてください。これはユーザーがコマンドを入力する場所を理解するのに役立ちます。例えば:

code-example.mdx
```bash filename="Terminal"
npx create-next-app
```

ドキュメンテーションのほとんどの例は tsx と jsx で書かれていますが、いくつかは bash で書かれています。しかし、サポートされている任意の言語を使用することができます、ここに全リスト があります。

JavaScript code ブロックを書くとき、次の言語と拡張組み合わせを使用します。

言語拡張子
JavaScript ファイルは JSX code を含む`jsx.js
JavaScript JSX なしのファイル`js.js
TypeScript ファイルと JSX`tsx.tsx
TypeScript ファイル(JSX なし)`ts.ts

TS と JS スイッチャー

TypeScript と JavaScript を切り替えるための言語切り替えを追加してください。Code ブロックは、ユーザーに対応するために最初に TypeScript で、JavaScript version が必要です。

現在、我々は TS と JS の例を順番に書き、それらをswitcherプロップで link しています。

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

```


```jsx:app/page.js

```

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

Line Highlighting

コード行をハイライトすることができます。これは、コードの特定の部分に注意を引きたいときに便利です。highlightプロパティに数値を渡すことで行をハイライトできます。

単数行: highlight={1}

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>
}

Icons

次のアイコンは、docs 内で使用するために利用可能です：

mdx-icon.mdx
<Check size={18} />
<Cross size={18} />

Output:

私たちはドキュメントで絵文字を使用しません。

Notes

重要だが不可欠ではない情報については、notes を使用してください。notes は、ユーザーがメインコンテンツから気を散らすことなく情報を追加するのに適しています。

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.

Output:

Good to know: これは一行のメモです。

Good to know:

  • 私たちはまた、複数行のメモにこのフォーマットを使用します。
  • 時折、知っておく価値のあるアイテムや覚えておくべきアイテムが複数存在します。

関連リンクは、論理的な next ステップへのリンクを追加することで、ユーザーの学習旅行を案内します。

  • リンクは、ページのメインコンテンツの下のカードで表示されます。
  • 子ページを持つページに対しては、リンクが自動的に生成されます。例えば、Optimizingセクションには、すべての子ページへのリンクがあります。

ページの metadata 内の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
---

ネストされたフィールド

項目必須?Description
titleオプショナルカードリストのタイトル。default は Next Steps です。
descriptionオプショナルカードリストの description 。
links必項他のドキュメントページへのリンクのリスト。各リストアイテムは相対的な URL path (最初のスラッシュを除く)であるべきです。例：app/api-reference/file-conventions/page

Diagrams

ダイアグラムは複雑な概念を説明するのに非常に有効です。私たちはFigma を使用してダイアグラムを作成し、Vercel のデザインガイドに従っています。

現在の図は私たちのプライベートな Next.js サイトの/publicフォルダに live しています。図を更新したり追加したりしたい場合は、ご自身のアイデアを用いてGitHub issue を開いてください。

Custom Components and HTML

これらはドキュメンテーションで利用可能な React Component です：<Image /> (next/image)、<PagesOnly />、<AppOnly />、<Cross />、そして <Check />です。ドキュメンテーションでは <details> タグを除いて、生の HTML は許可していません。

新しい Component のアイデアがある場合は、GitHub issue を開いてください。

Style Guide

このセクションには、テクニカルライティングが初めての人々のためのドキュメンテーションを作成するためのガイドラインが含まれています。

ページテンプレート

私たちは厳密な template(テンプレート)をページに持っていませんが、ドキュメント全体で繰り返し見るページセクションがあります：

  • 概要: ページの最初の段落は、その機能が何であり、何に使用されるかをユーザーに伝えるべきです。その後、最小の作業例またはその API reference を続けます。
  • 規約： 機能に規約がある場合、ここで説明するべきです。
  • 例示: この機能がさまざまなユースケースでどのように使用できるかを示します。
  • API テーブル: API ページには、可能な場合にはセクションへのジャンプリンクを含む概要テーブルをページの最後に配置する必要があります。
  • Next ステップ(関連リンク)：ユーザーの学習旅行をガイドするために関連ページへのリンクを追加します。

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

ページ type

Docs のページは、Conceptual と Reference の 2 つのカテゴリに分けられています。

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

Good to know: あなたが貢献しているページによっては、異なる声や style に従う必要があるかもしれません。たとえば、概念的なページはより教育的で、ユーザーに話しかけるときには you という単語を使います。参照ページはより技術的で、"create, update, accept"のような命令形の単語を多く使い、 you という単語を省略する傾向があります。

Voice

ここには、ドキュメンテーション全体で一貫した style とボイスを維持するためのいくつかのガイドラインがあります：

  • 明確で簡潔な文章を書きましょう。tangents を避けてください。
    • もし、あなたがコンマをたくさん使っていることに気付いたら、その文を複数の文に分けるか、リストを使うことを検討してみてください。
    • 複雑な言葉をもっと簡単なものに置き換えてください。例えば、utilize の代わりにuse を使う。
  • この言葉を注意深く使用してください。それは曖昧で混乱を招く可能性があります。主語が不明確な場合、主語を繰り返すことを恐れないでください。
    • 例えば、Next.js は React を使用しますは、Next.js はこれを使用しますの代わりになります。
  • 能動態を受動態の代わりに使ってください。能動的な文章の方が読みやすいです。
    • たとえば、Next.js は React を使うは React は Next.js によって使われるの代わりに使います。もしあなたがwasやbyのような言葉を使っていると、受動態を使っている可能性があります。
  • easy 、quick 、simple 、justなどのような言葉を使うのを避けてください。これは主観的で、ユーザーにとっては落胆させる可能性があります。
  • don't 、can't 、won'tなどの否定的な言葉は避けてください。これは読者にとって落胆させる可能性があります。
    • たとえば、"ページ間でリンクを作成するために Link component を使用できます" と言う代わりに、"ページ間のリンクを作成するために <a> タグを使わないでください" と言います。
  • second という表現(あなた/あなたの)を書きましょう。これはもっと個人的で魅力的です。
  • ジェンダーニュートラルな言葉を使用してください。視聴者を指すときは、developers、users、またはreadersを使用してください。
  • code の例を追加する場合、適切にフォーマットされており、正常に動作することを確認してください。

これらのガイドラインは全てを網羅しているわけではありませんが、始めるのに役立つはずです。もし技術文書作成についてさらに詳しく知りたいなら、Google Technical Writing Course をチェックしてみてください。

ドキュメントへの貢献と Next.js コミュニティの一部であることに感謝します！

当社サイトでは、Cookie を使用しています。各規約をご確認の上ご利用ください:
Cookie Policy, Privacy Policy および Terms of Use