# YAML 프론트매터 사용

YAML 프론트매터를 사용하여 버전 관리를 정의하고, 메타데이터를 추가하고, 문서의 레이아웃을 제어할 수 있습니다.

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

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

## YAML 프론트매터 밸류

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

* [`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)

* [`journeyTracks`](#journeytracks)

* [`type`](#type)

* [`communityRedirect`](#communityredirect)

* [`effectiveDate`](#effectivedate)

### `versions`

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

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

무료, Pro, 팀 및 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/enterprise-server@3.22/contributing/writing-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` 지원되는 레이아웃의 이름과 일치합니다. 신뢰할 수 있는 목록(예: `layoutNames`, , `src/frame/lib/frontmatter.ts`, `discovery-landing``journey-landing`, `bespoke-landing``category-landing`)을 참조하세요`toc-landing`.`inline`
* 선택 사항. 생략하면 `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`이며 맵 토픽 및 `false` 페이지에서 `index.md`입니다.
* 선택 사항.

### `allowTitleToDifferFromFilename`

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

### `changelog`

* 목적: 제품 방문 페이지([](https://github.blog/changelog/))에서 `components/landing`에서 가져온 항목 목록을 렌더링합니다. 한 가지 예외는 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 Desktop)이나 GitHub API를 의미합니다. 도구 선택기에 대한 자세한 내용은 [GitHub Docs에서 Markdown 및 Liquid 사용하는 방법](/ko/enterprise-server@3.22/contributing/writing-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
```

### `journeyTracks`

* 목적: 여정 랜딩 페이지의 여정을 정의합니다.
* 형식: `Array` 다음 속성이 있는 개체의 형식입니다.
  * `id` (필수): 여정의 고유 식별자입니다. ID는 단일 여정 방문 페이지 내의 여정에 대해서만 고유해야 합니다.
  * `title` (필수): 여정 제목 표시(Liquid 변수 지원)
  * `description` (선택 사항): 여정에 대한 설명(Liquid 변수 지원)
  * `timeCommitment` (선택 사항): 여정을 완료하는 데 걸리는 예상 시간(예: `2-4 hours`)입니다. 아티클 수 옆에 배지로 렌더링됩니다.
  * `guides` (필수): 이 과정을 구성하는 안내 개체의 배열입니다. 각 가이드 개체에는 다음이 있습니다.
    * `href` (필수): 문서의 경로
    * `alternativeNextStep` (선택 사항): 사용자에게 여정의 대체 경로를 안내하는 사용자 지정 텍스트입니다. Liquid 변수 및 `[AUTOTITLE]`.를 지원합니다.
* `layout: journey-landing`와 함께 사용하는 경우에만 적용됩니다.
* 선택 사항.

예시:

```yaml
journeyTracks:
  - id: 'getting_started'
    title: 'Getting started with GitHub Actions'
    description: 'Learn the basics of GitHub Actions.'
    timeCommitment: '2-4 hours'
    guides:
      - href: '/actions/quickstart'
      - href: '/actions/learn-github-actions'
        alternativeNextStep: 'Want to skip ahead? See [AUTOTITLE](/actions/using-workflows).'
      - href: '/actions/using-workflows'
  - id: 'advanced'
    title: 'Advanced GitHub Actions'
    description: 'Dive deeper into advanced features.'
    guides:
      - href: '/actions/using-workflows/workflow-syntax-for-github-actions'
      - href: '/actions/deployment/deploying-with-github-actions'
```

### `type`

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

### `communityRedirect`

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

### `effectiveDate`

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

> \[!NOTE]
> `effectiveDate` 프런트매터 값은 GitHub 직원만 사용할 수 있습니다.

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

YAML frontmatter에서 한 개의 작은따옴표(`''`)가 표시될 것으로 예상되었지만 두 개의 작은따옴표(`'`)가 나란히 표시되는 경우 이는 작은따옴표를 이스케이프하는 YAML 선호 방법입니다.

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

## 자동 생성된 미니 TOC

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

프론트매터 값을 [`showMiniToc`](#showminitoc)로 설정하여, `false` 미니 TOC가 문서에 표시되지 않도록 할 수 있습니다.

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

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

## 파일 이름

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

## 인덱스 페이지

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

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

## 홈 페이지

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

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