文件貢獻指南

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

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

為什麼要貢獻？

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

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

如何貢獻

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

GitHub 工作流程

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

須知：底層文件代碼位於一個私有代碼庫中，該代碼庫會同步到 Next.js 公共儲存庫。這意味著您無法在本地預覽文件。但是，在合併拉取請求後，您將在 nextjs.org 上看到您的更改。

撰寫 MDX

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

VSCode

本地預覽更改

VSCode 有一個內置的標記預覽器，您可以用來在本地查看編輯內容。要為 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 提供智能感知和語法高亮。
• Prettier：在保存時格式化 MDX 文件。

審核流程

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

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

提示：在提交 PR 前運行 pnpm prettier-fix 以運行 Prettier。

文件結構

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

文件結構反映了您在網站上看到的導航，默認情況下，導航項目按字母順序排序。但是，我們可以通過在文件夾或文件名前添加兩位數字 (00-) 來更改項目的順序。

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

04-functions
├── after.mdx
├── cacheLife.mdx
├── cacheTag.mdx
└── ...

但是，在 路由部分 中，文件前綴有兩位數字，按開發者應該學習這些概念的順序排序：

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

要快速找到頁面，您可以使用 ⌘ + P（Mac）或 Ctrl + P（Windows）在 VSCode 上打開搜索欄。然後，輸入您要查找的頁面的 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
version: experimental
---

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">About</Link>
}

在提交範例之前，始終在本地運行它們。這將確保代碼是最新的並且可以運行。

語言和文件名

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

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

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

在撰寫 JavaScript 代碼塊時，我們使用以下語言和擴展組合。

須知：

• 確保在 JavaScript 文件中使用 js 擴展與 JSX 代碼。
• 例如，```jsx filename="app/layout.js"

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">About</Link>
}

多行： highlight={1,3}

import Link from 'next/link'

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

行範圍： highlight={1-5}

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">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 />。我們不允許在文件中使用原始 HTML，除了 <details> 標籤。

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

風格指南

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

頁面模板

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

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

根據需要隨意添加這些部分。

頁面類型

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

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

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

寫作語氣

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

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

以上準則雖未涵蓋所有情況，但能幫助您快速上手。若想深入瞭解技術寫作，請參考 Google 技術寫作課程。

感謝您為文件做出貢獻，並成為 Next.js 社群的一員！