YAML 프론트매터에 대한 정보
YAML 프론트매터는 페이지에 메타데이터를 추가하는 방법을 제공하는 지킬에 의해 대중화된 저작 규칙입니다. 이는 GitHub Docs 내의 모든 마크다운 파일의 맨 위에 있는 키-값 콘텐츠 블록입니다. 파일에 대한 자세한 내용은 YAML 설명서를 참조하세요.
YAML 프런트매터 값
다음 앞부분 값은 에 대한 특별한 의미와 요구 사항을 가지고 있습니다.
또한 테스트 도구 모음에서 모든 페이지의 frontmatter의 유효성을 검사하는 데 사용하는 스키마도 있습니다.
자세한 내용은 lib/frontmatter.js
를 참조하세요.
versions
redirect_from
title
shortTitle
intro
permissions
product
layout
children
childGroups
featuredLinks
showMiniToc
allowTitleToDifferFromFilename
changelog
defaultPlatform
defaultTool
learningTracks
includeGuides
type
topics
communityRedirect
effectiveDate
versions
- 목적: 페이지가 적용되는 버전을 나타냅니다. 다양한 유형의 버전 관리에 대한 자세한 내용은 "버전 관리 설명서"를 참조하세요.
- 유형:
Object
. 허용되는 키는 제품 이름에 매핑되며lib/frontmatter.js
의versions
개체에서 찾을 수 있습니다. - 이 frontmatter 값은 현재 모든 페이지에 필요합니다.
*
는 버전에 대한 모든 릴리스를 나타내는 데 사용됩니다.- 모든
index.md
파일에 대해 존재해야 하지만 실제 값은 자식 요소를 기준으로 런타임에 계산됩니다.
이 앞부분 값은 문서 사이트에서 문서의 각 버전에 대한 "영구 링크"를 생성하는 데 사용됩니다. 자세한 내용은 퍼머링크에서 확인하세요.
Free, Pro, & Team 및 GitHub Enterprise Server 버전 3.11 이상에 적용되는 예:
title: About your personal dashboard
versions:
fpt: '*'
ghes: '>=3.11'
GitHub Enterprise Server에만 적용되는 예시:
title: Downloading your license
versions:
ghes: '*'
다양한 릴리스에 대한 페이지 버전을 관리할 수도 있습니다. 이렇게 하면 페이지의 버전이 Free, Pro, Team 및 GitHub Enterprise Server 버전 3.1 및 3.2로만 변경됩니다.
versions:
fpt: '*'
ghes: '>=3.1 <3.3'
redirect_from
- 목적: 이 페이지로 리디렉션해야 하는 URL을 나열합니다.
- 유형:
Array
- 선택 사항
예시:
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
자세한 내용은 "리디렉션 구성"을(를) 참조하세요.
title
- 목적: 렌더링된 페이지의
<title>
태그와 페이지 상단에 있는h1
요소에 사용할 사용자에게 친숙한 제목을 설정합니다. - 유형:
String
- 선택 사항. 생략하면 제네릭 값이
GitHub.com
또는GitHub Enterprise
와 같더라도 페이지<title>
이 설정됩니다.
shortTitle
- 목적: 이동 경로 및 탐색 요소에 사용할 페이지 제목의 축약된 변형입니다.
- 유형:
String
- 선택 사항. 생략하면
title
이 사용됩니다.
아티클 유형 | 최대 문자 길이 |
---|---|
기사 | 31 |
범주 | 27 |
맵 토픽 | 30 |
예시:
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
- 목적: 제품/범주/맵 토픽에 속하는 상대 링크를 나열합니다. 자세한 내용은 인덱스 페이지를 참조하세요.
- 유형:
Array
. 기본값은false
입니다. index.md
페이지에 필요합니다.
childGroups
- 목적: 자식을 홈페이지의 그룹으로 렌더링합니다. 자세한 내용은 홈페이지를 참조하세요.
- 유형:
Array
. 기본값은false
입니다. - 홈페이지
index.md
에 필요합니다.
featuredLinks
- 목적: 제품 방문 페이지 및 홈페이지에서 연결된 아티클의 제목 및 소개를 렌더링합니다.
- 유형:
Object
. - 선택 사항.
인기 있는 링크 목록은 방문 페이지에 "Popular"라는 제목 아래에 표시되는 링크입니다. 또는 featuredLinks.popularHeading
속성을 새 문자열로 설정하여 "Popular"라는 제목을 사용자 지정할 수 있습니다.
예시:
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를 참조하세요.
- 유형:
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에서 가져온 항목 목록을 렌더링합니다. 한 가지 예외는 Education이며 이는 https://github.blog/category/community/education에서 풀합니다. - 형식:
Object
, 속성:label
-- 존재해야 하며 GitHub Changelog에 사용된 레이블에 해당합니다.prefix
-- 문서 피드에서 생략해야 하는 각 변경 로그 제목을 시작하는 선택적 문자열입니다. 예를 들어 접두사GitHub Actions:
을 지정하면 문서 피드에서GitHub Actions: Some Title Here
와 같은 변경 로그 제목이Some Title Here
로 렌더링됩니다.
- 선택 사항.
defaultPlatform
- 목적: 페이지의 초기 플랫폼 선택을 재정의합니다. 이 frontmatter를 생략하면 판독기 운영 체제와 일치하는 플랫폼별 콘텐츠가 기본적으로 표시됩니다. 수동 선택이 더 합리적인 개별 페이지에 대해 이 동작을 변경할 수 있습니다. 예를 들어, 대부분의 GitHub Actions 실행자는 Linux를 사용하며 해당 운영 체제는 독자의 운영 체제와 독립적입니다.
- 형식:
String
, 다음 중 하나:mac
,windows
,linux
. - 선택 사항.
예시:
defaultPlatform: linux
defaultTool
- 목적: 페이지의 초기 도구 선택을 재정의합니다. 여기서 도구는 독자가 GitHub 작업을 위해 사용하는 애플리케이션(예: GitHub.com의 웹 UI, GitHub CLI 또는 GitHub 데스크톱) 또는 GitHub API를 나타냅니다. 도구 선택기에 대한 자세한 내용은 "GitHub Docs에서 Markdown 및 Liquid 사용하는 방법" 항목을 참조하세요. 이 앞부분을 생략하면 기본적으로 GitHub 웹 UI와 일치하는 도구별 콘텐츠가 표시됩니다. 사용자가 도구 탭을 클릭하여 도구 기본 설정을 표시한 경우 기본값 대신 사용자의 기본 설정이 적용됩니다.
- 형식:
String
, 다음 중 하나:webui
,cli
,desktop
,curl
,codespaces
,vscode
,importer_cli
,graphql
,powershell
,bash
,javascript
. - 선택 사항.
defaultTool: cli
learningTracks
- 목적: 제품의 하위 방문 페이지에서 학습 트랙 목록을 렌더링합니다.
- 유형:
String
. 여기서는data/learning-tracks/*.yml
에 정의된 학습 트랙의 이름을 참조해야 합니다. - 선택 사항
**참고: ** 추천 트랙은 학습 트랙 YAML의 특정 속성에 의해 설정됩니다. 자세한 내용은 README 파일을 참조하세요.
includeGuides
- 목적:
type
및topics
로 필터링 가능한 문서 목록을 렌더링합니다.layout: product-guides
와 함께 사용하는 경우에만 적용됩니다. - 유형:
Array
- 선택 사항.
예시:
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
- 목적: 아티클에서 다루는 토픽을 나타냅니다. 주제 추가에 대한 자세한 내용은 콘텐츠 모델을 참조하세요. 기존 토픽의 전체 목록은 허용된 토픽 파일에 있습니다. 아티클 frontmatter의 토픽과 허용 토픽 목록이 동기화되지 않으면 토픽 CI 테스트가 실패합니다.
- 형식:
String
의 배열 - 선택 사항: 각 문서에 토픽이 선호되지만 기존 문서에 아직 토픽이 없거나 새 문서에 토픽을 추가해도 가치를 더하지 못하는 경우가 있을 수 있습니다.
communityRedirect
- 목적: 바닥글의
Ask the GitHub community
링크에 대한 사용자 지정 링크 및 링크 이름을 설정합니다. - 유형:
Object
. 속성은name
및href
입니다. - 선택 사항.
effectiveDate
- 목적: 엔지니어링 팀이 자동으로 사용자에게 약관을 확인하라는 메시지를 다시 표시할 수 있도록 서비스 이용약관 문서의 유효 날짜를 설정합니다.
- 형식:
string
년-월-일(예: 2021-10-04은 2021년 10월 4일) - 선택 사항.
참고: effectiveDate
frontmatter 값은 GitHub 직원에게만 사용됩니다.
작은따옴표 이스케이프
YAML 프런트 매터에서 작은따옴표 하나('
)가 표시될 것으로 예상했지만 두 개(''
)가 나란히 표시되는 경우, 이는 작은따옴표를 이스케이프하는 YAML 권장 방법입니다.
또는 frontmatter 필드를 둘러싼 작은따옴표를 큰따옴표로 변경하고 내부 작은따옴표를 이스케이프하지 않은 채로 둘 수 있습니다.
자동 생성된 미니 TOC
모든 문서에는 문서의 모든 H2
항목에 대한 링크가 포함된 자동 생성된 "이 문서" 섹션인 TOC(미니 목차)가 표시됩니다. 미니 TOC에는 헤더만 H2
포함됩니다. 문서에서 H3
또는 H4
머리글을 사용해서 특정 구역만 특정 작업과 관련된 방식으로 정보를 나누는 경우, 구역 목차를 사용하여 사용자가 가장 관련성이 큰 콘텐츠로 이동하도록 도울 수 있습니다.
프런트 맵 값을 사용하여 showMiniToc
미니 TOC가 아티클에 표시되지 않도록 할 false
수 있습니다.
미니 TOC는 제품 방문 페이지, 범주 방문 페이지 또는 맵 토픽 페이지에 표시되지 않습니다.
마크다운 소스에 하드코딩된 "이 문서에서" 섹션을 추가하지 않으면 페이지에 중복된 미니 TOC가 표시됩니다.
파일 이름
새 아티클을 추가할 때 파일 이름이 아티클의 title
frontmatter에서 사용하는 제목의 케밥 케이스 버전인지 확인합니다. 제목에 문장 부호가 있는 경우(예: "GitHub 청구 계획") 까다로울 수 있습니다. 테스트는 제목과 파일 이름 간의 불일치에 플래그를 지정합니다. 지정된 아티클에 대한 이 요구 사항을 재정의하려면 allowTitleToDifferFromFilename
frontmatter를 추가할 수 있습니다.
인덱스 페이지
인덱스 페이지는 문서 사이트의 목차 파일입니다. 모든 제품, 범주 및 지도 주제 하위 디렉터리에 index.md
파일이 있어 내용 개요와 모든 하위 문서에 대한 링크를 제공합니다. 각 index.md
에는 제품, 범주 또는 맵 토픽의 자식 페이지에 대한 상대 링크 목록이 있는 children
frontmatter 속성이 포함되어야 합니다. 인덱스 페이지에는 versions
프런트 매터 속성이 있어야 하며, 실제 값은 하위 문서의 버전에 따라 런타임에 컴퓨팅됩니다.
참고: 해당 사이트는 children
프런트 매터에 포함된 경로에 대해서만 알고 있습니다. 디렉터리 또는 문서가 있지만 children
에 포함되지 않은 경우, 해당 경로는 404로 반환됩니다.
홈 페이지
홈페이지는 문서 사이트의 기본 목차 파일입니다. 홈페이지에는 모든 인덱스 페이지와 마찬가지로 children
의 전체 목록이 있어야 하지만 주 콘텐츠 영역에서 강조 표시될 childGroups
frontmatter 속성도 지정해야 합니다.
childGroups
은 그룹에 대한 name
을 포함하는 매핑 배열, 그룹에 대한 선택적 icon
및 children
배열입니다. 배열의 children
은 children
frontmatter 속성에 있어야 합니다.
새 제품 가이드 페이지 만들기
제품 가이드 페이지(예: GitHub Actions 가이드 페이지)를 만들려면, 다음과 같은 특정 프런트 매터 값을 사용하여 기존 Markdown 파일을 만들거나 수정하세요.
- 다음을 참조하여 제품 가이드 페이지 템플릿을 사용하세요
layout: product-guides
. learningTracks
에 학습 트랙을 포함하세요. 선택 사항.includeGuides
와(과) 같이 포함할 문서를 정의하세요. 선택 사항.
학습 트랙을 사용하는 경우 data/learning-tracks/*.yml
에서 정의해야 합니다.
includeGuides
를 사용하는 경우 이 목록의 각 아티클의 frontmatter에 topics
및 type
이 있는지 확인합니다.