YAML 프론트매터 사용

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

이 문서의 내용

YAML 프론트매터에 대한 정보

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

YAML 프런트매터 값

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

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에 필요합니다.
  • 목적: 제품 방문 페이지 및 홈페이지에서 연결된 아티클의 제목 및 소개를 렌더링합니다.
  • 유형: 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이 있는지 확인합니다.