跳到內容
Next.js 文件社群貢獻指南

文件貢獻指南

歡迎來到 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 檔案中

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頁面的 <h1> 標題，用於 SEO 和 OG 圖片。
描述頁面描述，用於 <meta name="description"> 標籤進行 SEO。
required-fields.mdx
---
title: Page Title
description: Page Description
---

通常的做法是將頁面標題限制為 2-3 個單詞（例如“最佳化圖片”），將描述限制為 1-2 句話（例如“瞭解如何在 Next.js 中最佳化圖片”）。

可選欄位

以下欄位是可選的

欄位描述
nav_title覆蓋導航中的頁面標題。當頁面標題過長無法完全顯示時非常有用。如果未提供，則使用 title 欄位。
source將內容拉取到共享頁面。請參閱 共享頁面。
related文件底部的相關頁面列表。這些將自動轉換為卡片。請參閱 相關連結。
version開發階段。例如 experimental、legacy、unstable、RC
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
version: experimental
---

App 和 Pages 文件

由於App Router和Pages Router中的大部分功能完全不同，它們的文件分別儲存在不同的部分（02-app和03-pages）。然而，它們之間有一些共享功能。

共享頁面

為了避免內容重複和內容不同步的風險，我們使用 source 欄位將內容從一個頁面拉取到另一個頁面。例如，<Link> 元件在 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> 元件有一個 shallow 屬性，該屬性僅在 Pages 中可用，而在 App 中不可用。

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

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.

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

程式碼塊

程式碼塊應包含可以複製貼上的最小工作示例。這意味著程式碼應該能夠在沒有任何額外配置的情況下執行。

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

app/page.tsx
import Link from 'next/link'
 
export default function Page() {
  return <Link href="/about">About</Link>
}

在提交示例之前，請務必在本地執行它們。這將確保程式碼是最新的且正常工作。

語言和檔名

程式碼塊應包含一個標題，其中包括語言和 filename。新增 filename 屬性以渲染一個特殊的終端圖示，這有助於使用者瞭解在哪裡輸入命令。例如：

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"

TS 和 JS 切換器

新增語言切換器以在 TypeScript 和 JavaScript 之間切換。程式碼塊應以 TypeScript 為優先，並提供 JavaScript 版本以適應使用者。

目前，我們一個接一個地編寫 TS 和 JS 示例，並用 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
> **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.

輸出

須知：這是一條單行註釋。

須知:

  • 我們也使用這種格式來表示多行註釋。
  • 有時會有多項值得了解或記住的內容。

相關連結透過新增指向邏輯下一步的連結來指導使用者的學習旅程。

  • 連結將顯示在頁面主要內容下方的卡片中。
  • 擁有子頁面的頁面將自動生成連結。

使用頁面元資料中的 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
---

巢狀欄位

欄位必填？描述
title可選卡片列表的標題。預設為下一步。
描述可選卡片列表的描述。
連結必需指向其他文件頁面的連結列表。每個列表項都應是相對 URL 路徑（不帶前導斜槓），例如 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 文件中，概念性頁面位於構建您的應用程式部分。
  • 參考頁面用於解釋特定的 API。它們通常更短、更集中。在 Next.js 文件中，參考頁面位於API 參考部分。

須知：根據您所貢獻的頁面，您可能需要遵循不同的語氣和風格。例如，概念性頁面更具指導性，並使用“您”一詞來稱呼使用者。參考頁面更具技術性，它們使用更多祈使詞，如“建立、更新、接受”，並且傾向於省略“您”字。

語氣

以下是用於在文件中保持一致風格和語氣的指南：

  • 撰寫清晰、簡潔的句子。避免離題。
    • 如果您發現自己使用了大量的逗號，請考慮將句子拆分成多個句子或使用列表。
    • 將複雜的詞語替換為簡單的詞語。例如，使用“使用”（use）而不是“利用”（utilize）。
  • 注意使用“這”（this）一詞。它可能模稜兩可且令人困惑，如果意思不明確，不要害怕重複句子的主語。
    • 例如，應該說“Next.js 使用 React”，而不是“Next.js 使用這個”。
  • 使用主動語態而不是被動語態。主動語態的句子更容易閱讀。
    • 例如，“Next.js 使用 React”而不是“React 被 Next.js 使用”。如果您發現自己使用了“被”（was）和“由”（by）等詞，您可能正在使用被動語態。
  • 避免使用“容易”、“快速”、“簡單”、“僅僅”等詞。這些詞帶有主觀性，可能會讓使用者感到氣餒。
  • 避免使用“不”、“不能”、“不會”等否定詞。這可能會讓讀者感到沮喪。
    • 例如，使用“您可以使用 Link 元件在頁面之間建立連結”，而不是“不要使用 <a> 標籤在頁面之間建立連結”。
  • 以第二人稱（你/你的）寫作。這樣更具個性和吸引力。
  • 使用性別中立的語言。指代受眾時，使用“開發者”、“使用者”或“讀者”。
  • 如果新增程式碼示例，請確保它們格式正確且可執行。

雖然這些指南並非詳盡無遺，但它們應該能幫助您入門。如果您想深入瞭解技術寫作，請檢視 Google 技術寫作課程。

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