文件貢獻指南

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

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
└── ...

---
title: Page Title
description: Page Description
---

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

---
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 屬性，它僅在頁面路由器 中可用，而在應用程式路由器 中則不可用。

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

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> 元件本身。

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

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

語言和檔案名稱

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

TS 和 JS 切換器

code-example.mdx

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

輸出

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

注意事項

對於重要但不關鍵的資訊，請使用注意事項。注意事項是一種在不干擾使用者閱讀主要內容的情況下新增資訊的好方法。

> **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.

輸出

貼心小提醒：這是單行注意事項。

貼心小提醒:

• 我們也使用這種格式撰寫多行注意事項。
• 有時有多個值得了解或牢記的項目。

相關連結」區段具有指向其所有子頁面的連結。

使用頁面 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
---

巢狀欄位

圖表

圖表是解釋複雜概念的好方法。我們使用 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 參考區塊。

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

語氣

以下是一些在整個文件中保持一致風格和語氣的指導方針

• 撰寫清晰簡潔的句子。避免離題。
  • 如果您發現自己使用了許多逗號，請考慮將句子分成多個句子或使用列表。
  • 將複雜的詞語替換成更簡單的詞語。例如，使用「使用」而不是「利用」。
• 小心使用「此」字。它可能模稜兩可且令人困惑，如果不清楚，不要害怕重複句子的主語。
  • 例如，使用「Next.js 使用 React」而不是「Next.js 使用此」。
• 使用主動語態而不是被動語態。主動語態的句子更容易閱讀。
  • 舉例來說，應使用 _Next.js 使用 React_ 而不是 _React 被 Next.js 使用_。如果您發現自己使用了像是 _被_ 和 _由_ 等詞彙，您可能正在使用被動語態。
• 避免使用像是 _簡單_、_快速_、_容易_、_只要_ 等等的詞彙。這些詞彙帶有主觀意識，可能會讓使用者感到氣餒。
• 避免使用負面詞彙，例如 _不要_、_不能_、_不會_ 等等。這可能會讓讀者感到氣餒。
  • 例如，使用 _「您可以使用 Link 元件來建立頁面之間的連結」_ 而不是 _「不要使用 <a> 標籤來建立頁面之間的連結」_。
• 以第二人稱（您/您的）寫作。這樣更親切且更具吸引力。
• 使用性別中立的語言。在指稱讀者時，使用 _開發者_、_使用者_ 或 _讀者_。
• 如果要新增程式碼範例，請確保它們格式正確且可以正常運作。

雖然這些準則並非詳盡無遺，但它們應該可以幫助您入門。如果您想深入了解技術寫作，請查看 Google 技術寫作課程。

感謝您為文件貢獻，並成為 Next.js 社群的一份子！