文件貢獻指南

歡迎閱讀 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 和 Pages 中的行為大致相同。與其重複內容，我們可以從 app/.../link.mdx 拉取內容到 pages/.../link.mdx：

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

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

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

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

這樣我們只需在一處編輯內容，變更就會反映在兩個章節中。

共享內容

在共享頁面中，有時可能會有僅適用於 App Router 或 Pages Router 的內容。例如，<Link> 元件的 shallow 屬性僅在 Pages 中可用，而在 App 中不可用。

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

此內容在 App 和 Pages 之間共享。

<PagesOnly>

此內容僅在 Pages 文件中顯示。

</PagesOnly>

此內容在 App 和 Pages 之間共享。

您可能會在範例和程式碼區塊中使用這些元件。

程式碼區塊

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

例如，如果要展示如何使用 <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 issue 提出您的想法。

自訂元件與 HTML

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

如有新元件的想法，請開一個 GitHub issue。

風格指南

本節包含針對技術寫作新手的文件撰寫指南。

頁面模板

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

• 概述：頁面第一段應告訴使用者該功能是什麼及其用途。隨後提供最小可行範例或其 API 參考。
• 慣例：如果功能有慣例，應在此處說明。
• 範例：展示功能在不同使用情境下的應用。
• API 表格：API 頁面應在頁面底部提供概述表格（盡可能包含跳轉至章節的連結）。
• 下一步（相關連結）：添加相關頁面連結以引導使用者的學習路徑。

請根據需要添加這些章節。

頁面類型

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

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

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

寫作語氣

以下是一些維持文件風格與語氣一致性的準則：

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

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

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