문서 기여 가이드

Next.js 문서 기여 가이드에 오신 것을 환영합니다! 여러분이 여기 계신 것을 기쁘게 생각합니다.

이 페이지는 Next.js 문서를 편집하는 방법에 대한 지침을 제공합니다. 우리의 목표는 커뮤니티의 모든 사람이 문서에 기여하고 개선할 수 있도록 권한을 부여하는 것입니다.

왜 기여해야 하나요?

오픈소스 작업은 결코 끝나지 않으며, 문서도 마찬가지입니다. 문서에 기여하는 것은 초보자들이 오픈소스에 참여하는 좋은 방법이며, 경험 있는 개발자들이 더 복잡한 주제를 명확히 하면서 커뮤니티와 지식을 공유하는 방법이기도 합니다.

Next.js 문서에 기여함으로써, 여러분은 모든 개발자를 위한 더 강력한 학습 자원을 구축하는 데 도움을 주고 있습니다. 오타를 발견했든, 혼란스러운 섹션을 발견했든, 특정 주제가 누락되었다는 것을 깨달았든, 여러분의 기여는 환영받고 감사히 여겨집니다.

기여 방법

문서 내용은 Next.js 저장소에서 찾을 수 있습니다. 기여하려면 GitHub에서 직접 파일을 편집하거나 저장소를 복제하여 로컬에서 파일을 편집할 수 있습니다.

GitHub 워크플로우

GitHub을 처음 사용하는 경우, 저장소를 포크하고, 브랜치를 생성하고, 풀 리퀘스트를 제출하는 방법을 배우려면 GitHub 오픈소스 가이드를 읽는 것을 추천합니다.

알아두면 좋은 점: 기본 문서 코드는 Next.js 공개 저장소와 동기화되는 비공개 코드베이스에 있습니다. 이는 로컬에서 문서를 미리 볼 수 없다는 것을 의미합니다. 그러나 풀 리퀘스트를 병합한 후에는 nextjs.org에서 변경 사항을 볼 수 있습니다.

MDX 작성하기

문서는 JSX 구문을 지원하는 마크다운 형식인 MDX로 작성됩니다. 이를 통해 문서에 React 컴포넌트를 포함할 수 있습니다. 마크다운 구문에 대한 간단한 개요는 GitHub 마크다운 가이드를 참조하세요.

VSCode

로컬에서 변경 사항 미리보기

VSCode에는 로컬에서 편집 내용을 볼 수 있는 내장 마크다운 미리보기 기능이 있습니다. MDX 파일에 대해 미리보기를 활성화하려면 사용자 설정에 구성 옵션을 추가해야 합니다.

명령 팔레트를 열고 (⌘ + ⇧ + P - Mac 또는 Ctrl + Shift + P - Windows) 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 참조에서는 개발자가 특정 함수를 쉽게 찾을 수 있도록 페이지가 알파벳순으로 정렬되어 있습니다:

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)를 사용하여 검색 창을 열 수 있습니다. 그런 다음 찾고자 하는 페이지의 슬러그를 입력하세요. 예: defining-routes

왜 매니페스트를 사용하지 않나요?

문서 내비게이션을 생성하는 또 다른 인기 있는 방법인 매니페스트 파일 사용을 고려했지만, 매니페스트가 파일과 빠르게 동기화되지 않는다는 것을 발견했습니다. 파일 시스템 라우팅은 문서의 구조에 대해 생각하도록 강제하며 Next.js에 더 자연스럽게 느껴집니다.

메타데이터

각 페이지의 상단에는 세 개의 대시로 구분된 메타데이터 블록이 있습니다.

필수 필드

다음 필드는 필수입니다:

필드	설명
`title`	페이지의 `<h1>` 제목, SEO 및 OG 이미지에 사용됩니다.
`description`	페이지의 설명, SEO를 위해 `<meta name="description">` 태그에 사용됩니다.

required-fields.mdx

---
title: 페이지 제목
description: 페이지 설명
---

페이지 제목은 2-3단어로 제한하고(예: 이미지 최적화) 설명은 1-2문장으로 제한하는 것이 좋습니다(예: Next.js에서 이미지를 최적화하는 방법 알아보기).

선택적 필드

다음 필드는 선택 사항입니다:

필드	설명
`nav_title`	내비게이션에서 페이지의 제목을 재정의합니다. 페이지 제목이 너무 길어 맞지 않을 때 유용합니다. 제공되지 않으면 `title` 필드가 사용됩니다.
`source`	공유 페이지에 콘텐츠를 가져옵니다. 공유 페이지를 참조하세요.
`related`	문서 하단에 관련 페이지 목록을 표시합니다. 이들은 자동으로 카드로 변환됩니다. 관련 링크를 참조하세요.

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

`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
---
 
{/* 이 페이지를 편집하지 마세요. */}
{/* 이 페이지의 내용은 위의 소스에서 가져옵니다. */}

따라서 한 곳에서 콘텐츠를 편집하고 두 섹션 모두에 반영되도록 할 수 있습니다.

공유 콘텐츠

공유 페이지에서는 때때로 App Router 또는 Pages Router에만 해당하는 콘텐츠가 있을 수 있습니다. 예를 들어, <Link> 컴포넌트에는 Pages에서만 사용 가능하고 App에서는 사용할 수 없는 shallow prop이 있습니다.

콘텐츠가 올바른 라우터에만 표시되도록 하기 위해 <AppOnly> 또는 <PagesOnly> 컴포넌트로 콘텐츠 블록을 감쌀 수 있습니다:

app/.../link.mdx

이 내용은 App과 Pages 간에 공유됩니다.
 
<PagesOnly>
 
이 내용은 Pages 문서에만 표시됩니다.
 
</PagesOnly>
 
이 내용은 App과 Pages 간에 공유됩니다.

이러한 컴포넌트는 주로 예제와 코드 블록에 사용될 것입니다.

코드 블록

코드 블록은 복사하여 붙여넣을 수 있는 최소한의 작동 예제를 포함해야 합니다. 이는 코드가 추가 구성 없이 실행될 수 있어야 함을 의미합니다.

예를 들어, <Link> 컴포넌트 사용 방법을 보여주는 경우 import 문과 <Link> 컴포넌트 자체를 포함해야 합니다.

app/page.tsx

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

예제를 커밋하기 전에 항상 로컬에서 실행해 보세요. 이렇게 하면 코드가 최신 상태이고 작동하는지 확인할 수 있습니다.

언어 및 파일 이름

코드 블록에는 언어와 filename이 포함된 헤더가 있어야 합니다. 명령을 입력할 위치를 사용자에게 안내하는 특별한 터미널 아이콘을 렌더링하려면 filename prop을 추가하세요. 예를 들어:

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 스위처

TypeScript와 JavaScript 간 전환을 위한 언어 스위처를 추가하세요. 코드 블록은 사용자를 수용하기 위해 TypeScript를 먼저 작성하고 JavaScript 버전을 제공해야 합니다.

현재는 TS와 JS 예제를 연속해서 작성하고 switcher prop으로 연결합니다:

code-example.mdx

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

알아두면 좋은 점: 향후에는 TypeScript 스니펫을 JavaScript로 자동 컴파일할 계획입니다. 그때까지는 transform.tools를 사용할 수 있습니다.

라인 강조

코드 라인을 강조 표시할 수 있습니다. 이는 코드의 특정 부분에 주의를 끌고 싶을 때 유용합니다. highlight prop에 숫자를 전달하여 라인을 강조 표시할 수 있습니다.

단일 라인: 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

> **알아두면 좋은 점**: 이것은 한 줄짜리 참고 사항입니다.
 
> **알아두면 좋은 점**:
>
> - 여러 줄 참고 사항에도 이 형식을 사용합니다.
> - 때로는 알아두거나 명심해야 할 여러 항목이 있습니다.

출력:

알아두면 좋은 점: 이것은 한 줄짜리 참고 사항입니다.

알아두면 좋은 점:

여러 줄 참고 사항에도 이 형식을 사용합니다.

때로는 알아두거나 명심해야 할 여러 항목이 있습니다.

필드	필수 여부	설명
`title`	선택 사항	카드 목록의 제목. 기본값은 다음 단계입니다.
`description`	선택 사항	카드 목록의 설명.
`links`	필수	다른 문서 페이지에 대한 링크 목록. 각 목록 항목은 상대 URL 경로여야 합니다(선행 슬래시 없이). 예: `app/api-reference/file-conventions/page`

다이어그램

다이어그램은 복잡한 개념을 설명하는 좋은 방법입니다. 우리는 Vercel의 디자인 가이드를 따라 Figma를 사용하여 다이어그램을 만듭니다.

현재 다이어그램은 비공개 Next.js 사이트의 /public 폴더에 있습니다. 다이어그램을 업데이트하거나 추가하고 싶다면, 아이디어와 함께 GitHub 이슈를 열어주세요.

커스텀 컴포넌트 및 HTML

문서에서 사용할 수 있는 React 컴포넌트는 다음과 같습니다: <Image /> (next/image), <PagesOnly />, <AppOnly />, <Cross />, 그리고 <Check />. <details> 태그를 제외하고는 문서에서 원시 HTML을 허용하지 않습니다.

새로운 컴포넌트에 대한 아이디어가 있다면 GitHub 이슈를 열어주세요.

스타일 가이드

이 섹션에는 기술 문서 작성이 처음인 사람들을 위한 문서 작성 지침이 포함되어 있습니다.

페이지 템플릿

페이지에 대한 엄격한 템플릿은 없지만, 문서 전반에 걸쳐 반복되는 페이지 섹션이 있습니다:

개요: 페이지의 첫 단락은 기능이 무엇이고 무엇에 사용되는지 사용자에게 알려야 합니다. 그 다음에는 최소한의 작동 예제 또는 API 참조가 따라옵니다.
규칙: 기능에 규칙이 있다면 여기에서 설명해야 합니다.
예제: 다양한 사용 사례로 기능을 사용하는 방법을 보여줍니다.
API 표: API 페이지에는 가능한 경우 섹션으로 이동할 수 있는 링크가 있는 개요 표가 페이지 맨 위에 있어야 합니다.
다음 단계 (관련 링크): 사용자의 학습 여정을 안내하기 위해 관련 페이지에 대한 링크를 추가합니다.

필요에 따라 이러한 섹션을 자유롭게 추가하세요.

페이지 유형

문서 페이지는 개념적 페이지와 참조 페이지 두 가지 카테고리로 나뉩니다.

개념적 페이지는 개념이나 기능을 설명하는 데 사용됩니다. 일반적으로 참조 페이지보다 길고 더 많은 정보를 포함합니다. Next.js 문서에서 개념적 페이지는 애플리케이션 구축하기 섹션에서 찾을 수 있습니다.
참조 페이지는 특정 API를 설명하는 데 사용됩니다. 일반적으로 더 짧고 집중적입니다. Next.js 문서에서 참조 페이지는 API 참조 섹션에서 찾을 수 있습니다.

알아두면 좋은 점: 기여하는 페이지에 따라 다른 어조와 스타일을 사용해야 할 수 있습니다. 예를 들어, 개념적 페이지는 더 교육적이며 사용자를 지칭할 때 you를 사용합니다. 참조 페이지는 더 기술적이며, "create, update, accept"와 같은 명령형 단어를 더 많이 사용하고 you라는 단어를 생략하는 경향이 있습니다.

어조

문서 전반에 걸쳐 일관된 스타일과 어조를 유지하기 위한 몇 가지 지침은 다음과 같습니다:

명확하고 간결한 문장을 작성하세요. 불필요한 설명은 피하세요.
- 콤마를 많이 사용하게 된다면, 문장을 여러 개로 나누거나 목록을 사용하는 것을 고려하세요.
- 복잡한 단어는 더 간단한 단어로 바꾸세요. 예를 들어, utilize 대신 use를 사용하세요.
this라는 단어를 사용할 때 주의하세요. 이 단어는 모호하고 혼란을 줄 수 있습니다. 문장의 주어가 명확하지 않다면, 주어를 반복하는 것을 두려워하지 마세요.
- 예를 들어, Next.js는 React를 사용합니다라고 하세요. Next.js는 이것을 사용합니다라고 하지 마세요.
수동태 대신 능동태를 사용하세요. 능동태 문장이 읽기 더 쉽습니다.
- 예를 들어, React is used by Next.js 대신 Next.js uses React를 사용하세요. was와 by와 같은 단어를 사용하고 있다면 수동태를 사용하고 있을 수 있습니다.
easy, quick, simple, just 등의 단어 사용을 피하세요. 이는 주관적이며 사용자를 낙담시킬 수 있습니다.
don't, can't, won't 등의 부정적인 단어 사용을 피하세요. 이는 독자를 낙담시킬 수 있습니다.
- 예를 들어, "페이지 간 링크를 만들 때 <a> 태그를 사용하지 마세요" 대신 *"Link 컴포넌트를 사용하여 페이지 간 링크를 만들 수 있습니다"*를 사용하세요.
2인칭(you/your)으로 작성하세요. 이는 더 개인적이고 참여도가 높습니다.
성 중립적 언어를 사용하세요. 청중을 지칭할 때 개발자, 사용자 또는 독자를 사용하세요.
코드 예제를 추가할 때는 올바르게 형식이 지정되고 작동하는지 확인하세요.

이 지침이 완전하지는 않지만, 시작하는 데 도움이 될 것입니다. 기술 문서 작성에 대해 더 자세히 알아보고 싶다면 Google 기술 문서 작성 과정을 확인해보세요.

문서에 기여해 주시고 Next.js 커뮤니티의 일원이 되어 주셔서 감사합니다!

커뮤니티 Pages Router 사용하기

문서 기여 가이드

왜 기여해야 하나요?

기여 방법

GitHub 워크플로우

MDX 작성하기

VSCode

로컬에서 변경 사항 미리보기

확장 프로그램

검토 과정

파일 구조

메타데이터

필수 필드

선택적 필드

App과 Pages 문서

공유 페이지

공유 콘텐츠

코드 블록

언어 및 파일 이름

TS와 JS 스위처

라인 강조

아이콘

참고 사항

관련 링크

중첩된 필드

다이어그램

커스텀 컴포넌트 및 HTML

스타일 가이드

페이지 템플릿

페이지 유형

어조

`App`과 `Pages` 문서