## YAML 프론트매터에 대한 정보

YAML 프론트매터는 페이지에 메타데이터를 추가하는 방법을 제공하는 지킬에 의해 대중화된 저작 규칙입니다.
이는 GitHub Docs 내의 모든 마크다운 파일의 맨 위에 있는 키-값 콘텐츠 블록입니다. 파일에 대한 자세한 내용은 [YAML 설명서](https://jekyllrb.com/docs/front-matter/)를 참조하세요.

## YAML 프런트매터 값

다음 앞부분 값은 에 대한 특별한 의미와 요구 사항을 가지고 있습니다.
또한 테스트 도구 모음에서 모든 페이지의 frontmatter의 유효성을 검사하는 데 사용하는 스키마도 있습니다.
자세한 내용은 [`lib/frontmatter.js`](https://github.com/github/docs/blob/main/src/frame/lib/frontmatter.js)를 참조하세요.

* [`versions`](#versions)
* [`redirect_from`](#redirect_from)
* [`title`](#title)
* [`shortTitle`](#shorttitle)
* [`intro`](#intro)
* [`permissions`](#permissions)
* [`product`](#product)
* [`layout`](#layout)
* [`children`](#children)
* [`childGroups`](#childgroups)
* [`featuredLinks`](#featuredlinks)
* [`showMiniToc`](#showminitoc)
* [`allowTitleToDifferFromFilename`](#allowtitletodifferfromfilename)
* [`changelog`](#changelog)
* [`defaultPlatform`](#defaultplatform)
* [`defaultTool`](#defaulttool)
* [`learningTracks`](#learningtracks)
* [`includeGuides`](#includeguides)
* [`type`](#type)
* [`topics`](#topics)
* [`communityRedirect`](#communityredirect)
* [`effectiveDate`](#effectivedate)

### `versions`

* 목적: 페이지가 적용되는 [버전](https://github.com/github/docs/blob/main/src/versions/lib/all-versions.ts)을 나타냅니다.
  다양한 유형의 버전 관리에 대한 자세한 내용은 [버전 관리 설명서](/ko/contributing/syntax-and-versioning-for-github-docs/versioning-documentation)를 참조하세요.
* 유형: `Object`. 허용되는 키는 제품 이름에 매핑되며 [`lib/frontmatter.js`](https://github.com/github/docs/blob/main/src/frame/lib/frontmatter.js)의 `versions` 개체에서 찾을 수 있습니다.
* 이 frontmatter 값은 현재 모든 페이지에 **필요합니다**.
* `*`는 버전에 대한 모든 릴리스를 나타내는 데 사용됩니다.
* 모든 `index.md` 파일에 대해 존재해야 하지만 실제 값은 자식 요소를 기준으로 런타임에 계산됩니다.

이 앞부분 값은 문서 사이트에서 문서의 각 버전에 대한 "영구 링크"를 생성하는 데 사용됩니다. 자세한 내용은 [퍼머링크](/ko/contributing/writing-for-github-docs/using-markdown-and-liquid-in-github-docs#permalinks)에서 확인하세요.

Free, Pro, & Team 및 GitHub Enterprise Server 버전 3.11 이상에 적용되는 예:

```yaml
title: About your personal dashboard
versions:
  fpt: '*'
  ghes: '>=3.11'
```

GitHub Enterprise Server에만 적용되는 예시:

```yaml
title: Downloading your license
versions:
  ghes: '*'
```

다양한 릴리스에 대한 페이지 버전을 관리할 수도 있습니다. 이렇게 하면 페이지의 버전이 Free, Pro, Team 및 GitHub Enterprise Server 버전 3.1 및 3.2로만 변경됩니다.

```yaml
versions:
  fpt: '*'
  ghes: '>=3.1 <3.3'
```

### `redirect_from`

* 목적: 이 페이지로 리디렉션해야 하는 URL을 나열합니다.
* 유형: `Array`
* 선택 사항

예시:

```yaml
title: Getting started with GitHub Desktop
redirect_from:
  - /articles/first-launch
  - /articles/error-github-enterprise-version-is-too-old
  - /articles/getting-started-with-github-for-windows
```

자세한 내용은 [리디렉션 구성](/ko/contributing/syntax-and-versioning-for-github-docs/configuring-redirects)을(를) 참조하세요.

### `title`

* 목적: 렌더링된 페이지의 `<title>` 태그와 페이지 상단에 있는 `h1` 요소에 사용할 사용자에게 친숙한 제목을 설정합니다.
* 유형: `String`
* **필수입니다**.

### `shortTitle`

* 목적: 이동 경로 및 탐색 요소에 사용할 페이지 제목의 축약된 변형입니다.
* 유형: `String`
* 선택 사항. 생략하면 `title`이 사용됩니다.

| 아티클 유형 | 최대 문자 길이 |
| ------ | -------- |
| 기사     | 31       |
| 범주     | 27       |
| 맵 토픽   | 30       |

예시:

```yaml
title: Contributing to projects with GitHub Desktop
shortTitle: Contributing to projects
```

### `intro`

* 목적: 페이지의 소개를 설정합니다. 이 문자열은 `title` 이후에 렌더링됩니다.
* 유형: `String`
* 선택 사항.

### `permissions`

* 목적: 문서의 사용 권한문을 설정합니다. 이 문자열은 `intro` 이후에 렌더링됩니다.
* 유형: `String`
* 선택 사항.

### `product`

* 목적: 아티클의 제품 설명선 설정 이 문자열은 `intro` 및 `permissions`문 이후에 렌더링됩니다.
* 유형: `String`
* 선택 사항.

### `layout`

* 목적: 적절한 페이지 레이아웃을 렌더링합니다.
* 형식: 레이아웃의 이름과 일치하는 `String`입니다.
  `components/landing`으로 명명된 레이아웃의 경우 값은 `product-landing`입니다.
* 선택 사항. 생략하면 `DefaultLayout` 사용됩니다.

### `children`

* 목적: 제품/범주/맵 토픽에 속하는 상대 링크를 나열합니다. 자세한 내용은 [인덱스 페이지](#index-pages)를 참조하세요.
* 유형: `Array`. 기본값은 `false`입니다.
* `index.md` 페이지에 필요합니다.

### `childGroups`

* 목적: 자식을 홈페이지의 그룹으로 렌더링합니다. 자세한 내용은 [홈페이지](#homepage)를 참조하세요.
* 유형: `Array`. 기본값은 `false`입니다.
* 홈페이지 `index.md`에 필요합니다.

### `featuredLinks`

* 목적: 제품 방문 페이지 및 홈페이지에서 연결된 아티클의 제목 및 소개를 렌더링합니다.
* 유형: `Object`.
* 선택 사항.

인기 있는 링크 목록은 방문 페이지에 "Popular"라는 제목 아래에 표시되는 링크입니다. 또는 `featuredLinks.popularHeading` 속성을 새 문자열로 설정하여 "Popular"라는 제목을 사용자 지정할 수 있습니다.

예시:

```yaml
featuredLinks:
  gettingStarted:
    - /path/to/page
  startHere:
    - /guides/example
  popular:
    - /path/to/popular/article1
    - /path/to/popular/article2
  popularHeading: An alternate heading to Popular
```

### `showMiniToc`

* 목적: 문서에 나머지 콘텐츠 위에 미니 목차(TOC)를 표시할지 여부를 나타냅니다. 자세한 내용은 [자동 생성된 미니 TOC](#autogenerated-mini-tocs)를 참조하세요.
* 유형: `Boolean`. 기본값은 아티클에서 `true`이며 맵 토픽 및 `index.md` 페이지에서 `false`입니다.
* 선택 사항.

### `allowTitleToDifferFromFilename`

* 목적: 페이지의 파일 이름과 다른 제목을 가질 수 있는지 여부를 나타냅니다. 예를 들어 `content/rest/reference/orgs.md`은 `Orgs` 대신 `Organizations`라는 제목이 있습니다. 이 frontmatter가 `true`로 설정된 페이지는 테스트에서 플래그가 지정되거나 `src/content-render/scripts/reconcile-filenames-with-ids.js`에 의해 업데이트되지 않습니다.
* 유형: `Boolean`. 기본값은 `false`입니다.
* 선택 사항.

### `changelog`

* 목적: 제품 방문 페이지(`components/landing`)에서 [GitHub Changelog](https://github.blog/changelog/)에서 가져온 항목 목록을 렌더링합니다. 한 가지 예외는 Education이며 이는 <https://github.blog/category/community/education에서> 풀합니다.
* 형식: `Object`, 속성:
  * `label`-- 존재해야 하며 [GitHub Changelog](https://github.blog/changelog/)에 사용된 레이블에 해당합니다.
  * `prefix` -- 문서 피드에서 생략해야 하는 각 변경 로그 제목을 시작하는 선택적 문자열입니다. 예를 들어 접두사 `GitHub Actions: `을 지정하면 문서 피드에서 `GitHub Actions: Some Title Here`와 같은 변경 로그 제목이 `Some Title Here`로 렌더링됩니다.
* 선택 사항.

### `defaultPlatform`

* 목적: 페이지의 초기 플랫폼 선택을 재정의합니다. 이 frontmatter를 생략하면 판독기 운영 체제와 일치하는 플랫폼별 콘텐츠가 기본적으로 표시됩니다. 수동 선택이 더 합리적인 개별 페이지에 대해 이 동작을 변경할 수 있습니다. 예를 들어, 대부분의 GitHub Actions 실행자는 Linux를 사용하며 해당 운영 체제는 독자의 운영 체제와 독립적입니다.
* 형식: `String`, 다음 중 하나: `mac`, `windows`, `linux`.
* 선택 사항.

예시:

```yaml
defaultPlatform: linux
```

### `defaultTool`

* 목적: 페이지의 초기 도구 선택을 재정의합니다. 여기서 도구는 독자가 GitHub 작업을 위해 사용하는 애플리케이션(예: GitHub.com의 웹 UI, GitHub CLI 또는 GitHub 데스크톱) 또는 GitHub API를 나타냅니다. 도구 선택기에 대한 자세한 내용은 [GitHub Docs에서 Markdown 및 Liquid 사용하는 방법](/ko/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs#tool-tags)을(를) 참조하세요. 이 앞부분을 생략하면 기본적으로 GitHub 웹 UI와 일치하는 도구별 콘텐츠가 표시됩니다. 사용자가 도구 탭을 클릭하여 도구 기본 설정을 표시한 경우 기본값 대신 사용자의 기본 설정이 적용됩니다.
* 형식: `String`, 다음 중 하나: `webui`, `cli`, `desktop`, `curl`, `codespaces`, `vscode`, `importer_cli`, `graphql`, `powershell`, `bash`, `javascript`.
* 선택 사항.

```yaml
defaultTool: cli
```

### `learningTracks`

* 목적: 제품의 하위 방문 페이지에서 학습 트랙 목록을 렌더링합니다.
* 유형: `String`. 여기서는 [`data/learning-tracks/*.yml`](https://github.com/github/docs/tree/main/data/learning-tracks)에 정의된 학습 트랙의 이름을 참조해야 합니다.
* 선택 사항

> \[!NOTE]
> 추천 트랙은 학습 트랙 YAML의 특정 속성에 의해 설정됩니다. 자세한 내용은 [README](https://github.com/github/docs/blob/main/data/learning-tracks/README.md) 파일을 참조하세요.

### `includeGuides`

* 목적: `type` 및 `topics`로 필터링 가능한 문서 목록을 렌더링합니다. `layout: product-guides`와 함께 사용하는 경우에만 적용됩니다.
* 유형: `Array`
* 선택 사항.

예시:

```yaml
includeGuides:
  - /actions/guides/about-continuous-integration
  - /actions/guides/setting-up-continuous-integration-using-workflow-templates
  - /actions/guides/building-and-testing-nodejs
  - /actions/guides/building-and-testing-powershell
```

### `type`

* 목적: 아티클 유형을 나타냅니다.
* 형식: `String`으로, `overview`, `quick_start`, `tutorial`, `how_to`, `reference`, `rai` 중 하나입니다.
* 선택 사항.

### `topics`

* 목적: 아티클에서 다루는 토픽을 나타냅니다. 주제 추가에 대한 자세한 내용은 콘텐츠 모델을 참조하세요. 기존 토픽의 전체 목록은 [허용된 토픽 파일](https://github.com/github/docs/blob/main/data/allowed-topics.js)에 있습니다. 아티클 frontmatter의 토픽과 허용 토픽 목록이 동기화되지 않으면 [토픽 CI 테스트](https://github.com/github/docs/blob/main/src/search/tests/topics.ts)가 실패합니다.
* 형식: `String`의 배열
* 선택 사항: 각 문서에 토픽이 선호되지만 기존 문서에 아직 토픽이 없거나 새 문서에 토픽을 추가해도 가치를 더하지 못하는 경우가 있을 수 있습니다.

### `communityRedirect`

* 목적: 바닥글의 `Ask the GitHub community` 링크에 대한 사용자 지정 링크 및 링크 이름을 설정합니다.
* 유형: `Object`. 속성은 `name` 및 `href`입니다.
* 선택 사항.

### `effectiveDate`

* 목적: 엔지니어링 팀이 자동으로 사용자에게 약관을 확인하라는 메시지를 다시 표시할 수 있도록 서비스 이용약관 문서의 유효 날짜를 설정합니다.
* 형식: `string` 년-월-일(예: 2021-10-04은 2021년 10월 4일)
* 선택 사항.

> \[!NOTE]
> `effectiveDate` frontmatter 값은 GitHub 직원에게만 사용됩니다.

## 작은따옴표 이스케이프

YAML 프런트 매터에서 작은따옴표 하나(`'`)가 표시될 것으로 예상했지만 두 개(`''`)가 나란히 표시되는 경우, 이는 작은따옴표를 이스케이프하는 YAML 권장 방법입니다.

또는 frontmatter 필드를 둘러싼 작은따옴표를 큰따옴표로 변경하고 내부 작은따옴표를 이스케이프하지 않은 채로 둘 수 있습니다.

## 자동 생성된 미니 TOC

모든 문서에는 문서의 모든 `H2`항목에 대한 링크가 포함된 자동 생성된 "이 문서" 섹션인 TOC(미니 목차)가 표시됩니다. 미니 TOC에는 헤더만 `H2` 포함됩니다. 문서에서 `H3` 또는 `H4` 머리글을 사용해서 특정 구역만 특정 작업과 관련된 방식으로 정보를 나누는 경우, [구역 목차](/ko/contributing/style-guide-and-content-model/style-guide#sectional-tocs)를 사용하여 사용자가 가장 관련성이 큰 콘텐츠로 이동하도록 도울 수 있습니다.

프런트 맵 값을 사용하여 [`showMiniToc`](#showminitoc) 미니 TOC가 아티클에 표시되지 않도록 할 `false`수 있습니다.

미니 TOC는 제품 방문 페이지, 범주 방문 페이지 또는 맵 토픽 페이지에 표시되지 않습니다.

마크다운 소스에 하드코딩된 "이 문서에서" 섹션을 추가하지 않으면 페이지에 중복된 미니 TOC가 표시됩니다.

## 파일 이름

새 아티클을 추가할 때 파일 이름이 아티클의 [`title`](#title) frontmatter에서 사용하는 제목의 [케밥 케이스](https://en.wikipedia.org/wiki/Letter_case#Special_case_styles) 버전인지 확인합니다. 제목에 문장 부호가 있는 경우(예: "GitHub 청구 계획") 까다로울 수 있습니다. 테스트는 제목과 파일 이름 간의 불일치에 플래그를 지정합니다. 지정된 아티클에 대한 이 요구 사항을 재정의하려면 [`allowTitleToDifferFromFilename`](#allowtitletodifferfromfilename) frontmatter를 추가할 수 있습니다.

## 인덱스 페이지

인덱스 페이지는 문서 사이트의 목차 파일입니다. 모든 제품, 범주 및 지도 주제 하위 디렉터리에 `index.md` 파일이 있어 내용 개요와 모든 하위 문서에 대한 링크를 제공합니다. 각 `index.md`에는 제품, 범주 또는 맵 토픽의 자식 페이지에 대한 상대 링크 목록이 있는 `children` frontmatter 속성이 포함되어야 합니다. 인덱스 페이지에는 `versions` 프런트 매터 속성이 있어야 하며, 실제 값은 하위 문서의 버전에 따라 런타임에 컴퓨팅됩니다.

> \[!NOTE]
> 해당 사이트는 `children` 프런트 매터에 포함된 경로에 대해서만 알고 있습니다. 디렉터리 또는 문서가 있지만 `children`에 포함되지 **않은** 경우, 해당 경로는 404로 반환됩니다.

## 홈 페이지

홈페이지는 문서 사이트의 기본 목차 파일입니다. 홈페이지에는 모든 [인덱스 페이지](#index-pages)와 마찬가지로 `children`의 전체 목록이 있어야 하지만 주 콘텐츠 영역에서 강조 표시될 `childGroups` frontmatter 속성도 지정해야 합니다.

`childGroups`은 그룹에 대한 `name`을 포함하는 매핑 배열, 그룹에 대한 선택적 `icon` 및 `children` 배열입니다. 배열의 `children`은 `children` frontmatter 속성에 있어야 합니다.

## 새 제품 가이드 페이지 만들기

제품 가이드 페이지(예: [GitHub Actions 가이드 페이지](/ko/actions/guides))를 만들려면, 다음과 같은 특정 프런트 매터 값을 사용하여 기존 Markdown 파일을 만들거나 수정하세요.

* 다음을 참조하여 제품 가이드 페이지 템플릿을 사용하세요 `layout: product-guides`.
* [`learningTracks`](#learningtracks)에 학습 트랙을 포함하세요. 선택 사항.
* [`includeGuides`](#includeguides)와(과) 같이 포함할 문서를 정의하세요. 선택 사항.

학습 트랙을 사용하는 경우 [`data/learning-tracks/*.yml`](https://github.com/github/docs/tree/main/data/learning-tracks)에서 정의해야 합니다.
`includeGuides`를 사용하는 경우 이 목록의 각 아티클의 frontmatter에 [`topics`](#topics) 및 [`type`](#type)이 있는지 확인합니다.