文件貢獻指南

歡迎來到 Next.js 文件貢獻指南！我們很高興您的加入。

本頁面提供如何編輯 Next.js 文件的說明。我們的目標是確保社群中的每個人都能輕鬆貢獻並改進我們的文件。

為什麼要貢獻？

開源工作永無止境，文件也是如此。貢獻文件是初學者參與開源的好方法，也是經驗豐富的開發者分享知識、釐清複雜主題的機會。

透過貢獻 Next.js 文件，您正在幫助我們為所有開發者建立更強大的學習資源。無論是發現拼寫錯誤、令人困惑的段落，還是意識到缺少特定主題，我們都歡迎並感謝您的貢獻。

如何貢獻

文件內容可以在 Next.js 儲存庫 中找到。要貢獻內容，您可以直接在 GitHub 上編輯文件，或克隆儲存庫後在本機編輯。

GitHub 工作流程

如果您是 GitHub 新手，我們建議閱讀 GitHub 開源指南 來學習如何分叉儲存庫、建立分支並提交拉取請求。

小提示：底層文件程式碼位於私有程式碼庫中，該程式碼庫會同步到 Next.js 公開儲存庫。這意味著您無法在本機預覽文件。但合併拉取請求後，您可以在 nextjs.org 上看到變更。

撰寫 MDX

文件使用 MDX 格式撰寫，這是一種支援 JSX 語法的 Markdown 格式。這讓我們能在文件中嵌入 React 元件。請參閱 GitHub Markdown 指南 快速了解 Markdown 語法。

VSCode

本機預覽變更

VSCode 內建 Markdown 預覽器，可用於在本機查看編輯內容。要為 MDX 檔案啟用預覽器，您需要在用戶設定中添加配置選項。

打開命令面板（Mac 上按 ⌘ + ⇧ + P 或 Windows 上按 Ctrl + Shift + P），搜尋 Preferences: Open User Settings (JSON)。

然後，在 settings.json 檔案中添加以下行：

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

再次打開命令面板，搜尋 Markdown: Preview File 或 Markdown: Open Preview to the Side。這將打開一個預覽窗口，您可以在其中查看格式化後的變更。

擴充功能

我們還推薦 VSCode 用戶安裝以下擴充功能：

• MDX：為 MDX 提供智能感知和語法高亮。
• Grammarly：文法與拼寫檢查工具。
• Prettier：在儲存時格式化 MDX 檔案。

審核流程

提交貢獻後，Next.js 或開發者體驗團隊將審核您的變更、提供反饋，並在準備就緒時合併拉取請求。

如有任何問題或需要進一步協助，請在 PR 的評論中告知我們。感謝您貢獻 Next.js 文件並成為我們社群的一員！

小技巧：提交 PR 前執行 pnpm prettier-fix 來運行 Prettier。

檔案結構

文件使用檔案系統路由。/docs 內的每個資料夾和檔案代表一個路由區段。這些區段用於生成 URL 路徑、導航和麵包屑導航。

檔案結構反映了您在網站上看到的導航，預設情況下，導航項目按字母順序排序。但我們可以通過在資料夾或檔案名稱前添加兩位數字 (00-) 來變更項目的順序。

例如，在 函數 API 參考 中，頁面按字母順序排序，因為這讓開發者更容易找到特定函數：

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

但在 路由部分 中，檔案前綴了兩位數字，按開發者學習這些概念的順序排序：

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

要快速找到頁面，您可以在 VSCode 上使用 ⌘ + P (Mac) 或 Ctrl + P (Windows) 打開搜尋欄。然後，輸入您要找的頁面的 slug。例如 defining-routes

為什麼不使用清單檔案？

我們考慮過使用清單檔案（另一種生成文件導航的流行方法），但發現清單檔案會很快與檔案不同步。檔案系統路由迫使我們思考文件的結構，並感覺更符合 Next.js 的原生特性。

元數據

每個頁面頂部都有一個由三個破折號分隔的元數據區塊。

必填欄位

以下欄位是必填的：

---
title: 頁面標題
description: 頁面描述
---

良好的做法是將頁面標題限制在 2-3 個單字（例如「優化圖片」），並將描述限制在 1-2 句話（例如「學習如何在 Next.js 中優化圖片」）。

選填欄位

以下欄位是選填的：

---
nav_title: 導航項目標題
source: app/building-your-application/optimizing/images
related:
  description: 參見圖片元件 API 參考。
  links:
    - app/api-reference/components/image
---

App 和 Pages 文件

由於應用路由器 (App Router) 和頁面路由器 (Pages Router) 中的大多數功能完全不同，它們的文件分別保存在不同的部分 (02-app 和 03-pages)。但有少數功能是兩者共用的。

共享頁面

為避免內容重複和不同步的風險，我們使用 source 欄位將一個頁面的內容拉入另一個頁面。例如，<Link> 元件在應用和頁面中的行為大致相同。與其重複內容，我們可以從 app/.../link.mdx 拉取內容到 pages/.../link.mdx：

---
title: <Link>
description: 關於 <Link> 元件的 API 參考。
---

此 API 參考將幫助您了解如何使用 Link 元件可用的屬性和配置選項。

---
title: <Link>
description: 關於 <Link> 元件的 API 參考。
source: app/api-reference/components/link
---

{/* 請勿編輯此頁面。 */}
{/* 此頁面的內容來自上述來源。 */}

這樣我們就可以在一個地方編輯內容，並讓變更反映在兩個部分中。

共享內容

在共享頁面中，有時可能會有應用路由器或頁面路由器專用的內容。例如，<Link> 元件有一個 shallow 屬性，僅在頁面中可用，而在應用中不可用。

為確保內容僅在正確的路由器中顯示，我們可以將內容區塊包裝在 <AppOnly> 或 <PagesOnly> 元件中：

此內容在應用和頁面之間共享。

<PagesOnly>

此內容僅在頁面文件中顯示。

</PagesOnly>

此內容在應用和頁面之間共享。

您可能會將這些元件用於範例和程式碼區塊。

程式碼區塊

程式碼區塊應包含可複製貼上的最小可行範例。這意味著程式碼應能在不進行任何額外配置的情況下運行。

例如，如果要展示如何使用 <Link> 元件，應包含 import 語句和 <Link> 元件本身。

import Link from 'next/link'

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

在提交之前，請始終在本機運行範例。這將確保程式碼是最新的且可運作。

語言和檔案名稱

程式碼區塊應有一個標頭，包含語言和 filename。添加 filename 屬性可渲染特殊的終端圖標，幫助用戶定位應輸入命令的位置。例如：

```bash filename="Terminal"
npx create-next-app
```

文件中的大多數範例都是用 tsx 和 jsx 撰寫的，少數用 bash。但您可以使用任何支援的語言，這裡是完整列表。

撰寫 JavaScript 程式碼區塊時，我們使用以下語言和副檔名組合。

TS 和 JS 切換器

添加語言切換器以在 TypeScript 和 JavaScript 之間切換。程式碼區塊應優先使用 TypeScript，並提供 JavaScript 版本以適應不同用戶。

目前，我們將 TS 和 JS 範例一個接一個地撰寫，並用 switcher 屬性連結它們：

```tsx filename="app/page.tsx" switcher

```

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

```

小提示：我們計劃未來自動將 TypeScript 片段編譯為 JavaScript。在此期間，您可以使用 transform.tools。

行高亮

可以高亮程式碼行。這在您想引起對程式碼特定部分的注意時很有用。您可以通過將數字傳遞給 highlight 屬性來高亮行。

單行： highlight={1}

import Link from 'next/link'

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

多行： highlight={1,3}

import Link from 'next/link'

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

行範圍： highlight={1-5}

import Link from 'next/link'

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

圖標

以下圖標可在文件中使用：

<Check size={18} />
<Cross size={18} />

輸出：

我們不在文件中使用表情符號。

註記

對於重要但不關鍵的資訊，請使用註記。註記是添加資訊而不分散用戶對主要內容注意力的好方法。

> **小提示**：這是單行註記。

> **小提示**：
>
> - 我們也使用這種格式進行多行註記。
> - 有時有多個值得了解或記住的事項。

輸出：

小提示：這是單行註記。

小提示：

• 我們也使用這種格式進行多行註記。
• 有時有多個值得了解或記住的事項。

相關連結

相關連結通過添加邏輯上的下一步連結來引導用戶的學習旅程。

• 連結將顯示在頁面主要內容下方的卡片中。
• 對於有子頁面的頁面，將自動生成連結。例如，優化 部分有指向其所有子頁面的連結。

使用頁面元數據中的 related 欄位建立相關連結。

---
related:
  description: 了解如何快速開始您的第一個應用程式。
  links:
    - app/building-your-application/routing/defining-routes
    - app/building-your-application/data-fetching
    - app/api-reference/file-conventions/page
---

嵌套欄位

圖表

圖表是解釋複雜概念的好方法。我們使用 Figma 建立圖表，遵循 Vercel 的設計指南。

圖表目前位於我們私有 Next.js 網站的 /public 資料夾中。如果您想更新或添加圖表，請打開一個 GitHub 問題 並提出您的想法。

自訂元件和 HTML

文件中可用的 React 元件有：<Image /> (next/image)、<PagesOnly />、<AppOnly />、<Cross /> 和 <Check />。除了 <details> 標籤外，我們不允許在文件中使用原始 HTML。

如果您有新元件的想法，請打開一個 GitHub 問題。

風格指南

本節包含為剛接觸技術寫作的人提供的文件撰寫指南。

頁面模板

雖然我們沒有嚴格的頁面模板，但您會在文件中看到重複的頁面部分：

• 概述： 頁面的第一段應告訴用戶該功能是什麼以及它的用途。接著是最小可行範例或其 API 參考。
• 慣例： 如果功能有慣例，應在此處解釋。
• 範例：展示功能在不同用例中的使用方式。
• API 表格：API 頁面應在頁面底部有一個概述表格，並盡可能包含跳轉到部分的連結。
• 下一步（相關連結）：添加相關頁面的連結以引導用戶的學習旅程。

請根據需要添加這些部分。

頁面類型

文件頁面分為兩大類別：概念性頁面與參考性頁面。

• 概念性頁面 用於解釋概念或功能，通常篇幅較長且包含更多資訊。在 Next.js 文件中，概念性頁面位於 建置你的應用程式 (Building Your Application) 章節。
• 參考性頁面 用於說明特定 API，通常更簡短且聚焦。在 Next.js 文件中，參考性頁面位於 API 參考 (API Reference) 章節。

小知識：根據你貢獻的頁面類型，可能需要採用不同的語氣和風格。例如，概念性頁面更具教學性，會使用「你」來稱呼使用者；參考性頁面則更技術性，常用「建立、更新、接受」等命令式詞彙，且傾向省略「你」這個字。

寫作語氣

以下是指引，幫助在文件中保持一致的風格與語氣：

• 撰寫清晰簡潔的句子，避免離題。
  • 如果發現句子中有過多逗號，可考慮拆分成多個句子或改用清單。
  • 用簡單詞彙替代複雜用語，例如用「使用」而非「利用 (utilize)」。
• 謹慎使用「這個」一詞，可能造成歧義。若語意不清，請直接重複主詞。
  • 例如：「Next.js 使用 React」而非「Next.js 使用這個」。
• 使用主動語態而非被動語態，主動句更易閱讀。
  • 例如：「Next.js 使用 React」而非「React 被 Next.js 使用」。若發現使用「被」或「由」等字，可能正在使用被動語態。
• 避免使用「簡單」、「快速」、「只要」等主觀詞彙，可能讓使用者感到挫折。
• 避免「不要」、「不能」、「不會」等否定詞，可能打擊讀者信心。
  • 例如：「你可以使用 Link 元件建立頁面連結」而非「不要用 <a> 標籤建立頁面連結」。
• 使用第二人稱（你/你的），更具親和力。
• 使用性別中立語言，提及讀者時可用「開發者」、「使用者」或「讀者」。
• 若新增程式碼範例，請確保格式正確且可運作。

這些指引雖未涵蓋所有情況，但能幫助你入門。若想深入技術寫作技巧，可參考 Google 技術寫作課程。

感謝你貢獻文件，成為 Next.js 社群的一員！