이 섹션의 다중 페이지 출력 화면임. 여기를 클릭하여 프린트.

문서 스타일 개요

1: 새로운 주제의 문서 작성
2: 콘텐츠 구성

이 섹션의 주제는 문서 작성 스타일, 컨텐츠 형식과 구성, 쿠버네티스 문서화에 적합하게 사용자 정의된 Hugo 사용 방법에 대한 가이드를 제공한다.

1 - 새로운 주제의 문서 작성

이 페이지는 쿠버네티스 문서에서 새로운 주제를 생성하는 방법을 보여준다.

시작하기 전에

PR 열기에 설명된 대로 쿠버네티스 문서 저장소의 포크(fork)를 생성하자.

페이지 타입 선택

새로운 주제 작성을 준비할 때는, 콘텐츠에 가장 적합한 페이지 타입을 고려하자.

페이지 타입 선택 지침
타입	설명
개념	개념 페이지는 쿠버네티스의 일부 측면을 설명한다. 예를 들어 개념 페이지는 쿠버네티스 디플로이먼트 오브젝트를 설명하고 배치, 확장 및 업데이트되는 동안 애플리케이션으로서 수행하는 역할을 설명할 수 있다. 일반적으로 개념 페이지는 일련의 단계가 포함되지 않지만 대신 태스크나 튜토리얼에 대한 링크를 제공한다. 개념 문서의 예로서 노드를 참조하자.
태스크	태스크 페이지는 단일 작업을 수행하는 방법을 보여준다. 아이디어는 독자가 페이지를 읽을 때 실제로 수행할 수 있는 일련의 단계를 제공하는 것이다. 태스크 페이지는 한 영역에 집중되어 있으면 짧거나 길 수 있다. 태스크 페이지에서 수행할 단계와 간단한 설명을 혼합하는 것은 괜찮지만, 긴 설명을 제공해야 하는 경우에는 개념 문서에서 수행해야 한다. 관련 태스크와 개념 문서는 서로 연결되어야 한다. 짧은 태스크 페이지의 예제는 저장소에 볼륨을 사용하도록 파드 구성을 참조하자. 더 긴 태스크 페이지의 예제는 활동성 및 준비성 프로브 구성을 참조하자.
튜토리얼	튜토리얼 페이지는 여러 쿠버네티스의 특징들을 하나로 묶어서 목적을 달성하는 방법을 보여준다. 튜토리얼은 독자들이 페이지를 읽을 때 실제로 할 수 있는 몇 가지 단계의 순서를 제공한다. 또는 관련 코드 일부에 대한 설명을 제공할 수도 있다. 예를 들어 튜토리얼은 코드 샘플의 연습을 제공할 수 있다. 튜토리얼에는 쿠버네티스의 특징에 대한 간략한 설명이 포함될 수 있지만 개별 기능에 대한 자세한 설명은 관련 개념 문서과 연결지어야 한다.

새 페이지 작성

작성하는 각각의 새 페이지에 대해 콘텐츠 타입을 사용하자. 문서 사이트는 새 콘텐츠 페이지를 작성하기 위한 템플릿 또는Hugo archetypes을 제공한다. 새로운 타입의 페이지를 작성하려면, 작성하려는 파일의 경로로 hugo new 를 실행한다. 예를 들면, 다음과 같다.

hugo new docs/concepts/my-first-concept.md

제목과 파일 이름 선택

검색 엔진에서 찾을 키워드가 있는 제목을 선택하자.제목에 있는 단어를 하이픈으로 구분하여 사용하는 파일 이름을 만들자.예를 들어HTTP 프록시를 사용하여 쿠버네티스 API에 접근 이라는 제목의 문서는 http-proxy-access-api.md라는 이름의 파일을 가진다."쿠버네티스"가 이미 해당 주제의 URL에 있기 때문에 파일 이름에 "쿠버네티스" 를 넣을 필요가 없다.예를 들면 다음과 같다.

   /docs/tasks/extend-kubernetes/http-proxy-access-api/

프론트 매터(front matter)에 항목 제목 추가

문서에서 프론트 매터 에 title 필드를 입력하자.프론트 매터는 페이지 상단의 3중 점선 사이에 있는 YAML 블록이다. 여기 예시가 있다.

---
title: HTTP 프록시를 사용하여 쿠버네티스 API에 접근
---

디렉터리 선택

페이지 타입에 따라 새로운 파일을 다음 중 하나의 하위 디렉터리에 넣자.

/content/en/docs/tasks/
/content/en/docs/tutorials/
/content/en/docs/concepts/

파일을 기존 하위 디렉터리에 넣거나 새 하위 디렉터리에 넣을 수 있다.

목차에 항목 배치

목차는 문서 소스의 디렉터리 구조를 사용하여 동적으로 작성된다. /content/en/docs/ 아래의 최상위 디렉터리는 최상위 레벨 탐색 기능을 생성하고, 하위 디렉터리는 각각 목차에 항목을 갖는다.

각 하위 디렉터리에는 _index.md 파일이 있으며 이는 해당 하위 디렉터리의 컨텐츠에 대한"홈" 페이지를 나타낸다. _index.md에는 템플릿이 필요없다. 그것은 하위 디렉터리의 항목에 대한 개요 내용을 포함할 수 있다.

디렉터리의 다른 파일들은 기본적으로 알파벳순으로 정렬된다. 이것은 거의 최적의 순서가 아니다. 하위 디렉터리에서 항목의 상대적 정렬을 제어하려면weight: 전문의 키를 정수로 설정하자. 일반적으로 우리는 나중에 항목을 추가하기 위해 10의 배수를 사용한다. 예를 들어 가중치가10인 항목은 가중치가 20인 항목보다 우선한다.

문서에 코드 포함

문서에 코드를 포함시키려면 마크다운 코드 블록 구문을 사용하여 파일에 코드를 직접 삽입하자. 다음 경우에 권장된다. (전체 목록은 아님)

kubectl get deploy mydeployment -o json | jq '.status'와 같은 명령어의 출력을 보여주는 코드.
시도해보기에는 적절하지 않은 코드. 예를 들어 특정 FlexVolume 구현에 따라 파드를 만들기 위해 YAML 파일을 포함할 수 있다.
더 큰 파일의 일부분을 강조하기 위한 불완전한 예제 코드.예를 들어 롤바인딩(RoleBinding) 에 대한 사용자 정의 방법을 설명할 때,문서 파일에서 직접 짧은 요약 정보를 제공할 수 있다.
사용자가 다른 이유로 시도하기 위한 것이 아닌 코드. 예를 들어kubectl edit 명령을 사용하여 리소스에 새 속성을 추가하는 방법을 설명할 때 추가할 만한 속성을 포함하는 간단한 예를 제공할 수 있다.

다른 파일의 코드 포함

문서에 코드를 포함시키는 또 다른 방법은 새로운 완전한 샘플 파일(또는 샘플 파일 그룹)을 만든 다음 문서의 샘플을 참조하는 것이다.일반적이고 재사용 가능하며 독자가 스스로 실행해 볼 수 있도록 하는 샘플 YAML 파일을 포함시키려면 이 방법을 사용하자.

YAML 파일과 같은 새로운 독립형 샘플 파일을 추가할 때<LANG>/examples/ 의 하위 디렉터리 중 하나에 코드를 배치하자. 여기서 <LANG>은 주제에 관한 언어이다. 문서 파일에서 code_sample 단축 코드(shortcode)를 사용하자.

{{% code_sample file="<RELPATH>/my-example-yaml>" %}}

여기서 <RELPATH> 는 examples 디렉터리와 관련하여 포함될 파일의 경로이다. 다음 Hugo 단축 코드(shortcode)는 /content/en/examples/pods/storage/gce-volume.yaml 에 있는 YAML 파일을 참조한다.

{{% code_sample file="pods/storage/gce-volume.yaml" %}}

구성 파일에서 API 오브젝트를 작성하는 방법 표시

구성 파일을 기반으로 API 오브젝트를 생성하는 방법을 보여주려면<LANG>/examples 아래의 하위 디렉터리 중 하나에 구성 파일을 배치하자.

문서에서 이 명령을 띄워보자.

kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml

참고:

<LANG>/examples 디렉터리에 새 YAMl 파일을 추가할 때 파일이<LANG>/examples_test.go 파일에도 포함되어 있는지 확인하자.웹 사이트의 Travis CI 는 PR이 제출될 때 이 예제를 자동으로 실행하여 모든 예제가 테스트를 통과하도록 한다.

이 기술을 사용하는 문서의 예로단일 인스턴스 스테이트풀 어플리케이션 실행을 참조하자.

문서에 이미지 추가

이미지 파일을 /images 디렉터리에 넣는다. 기본 이미지 형식은 SVG 이다.

다음 내용

페이지 콘텐츠 타입 사용에 대해 알아보기.
풀 리퀘스트 작성에 대해 알아보기.

2 - 콘텐츠 구성

이 사이트는 Hugo를 사용한다. Hugo에서, 콘텐츠 구성은 핵심 개념이다.

참고:

Hugo 팁: 콘텐츠 편집 세션을 시작할 때는 hugo server --navigateToChanged로 Hugo를 실행한다.

페이지 목록

페이지 순서

문서 사이드 메뉴, 문서 페이지 브라우저 등은 Hugo의 기본 정렬 순서를 사용하여 나열되며, 이 정렬 순서는 weight(1부터 시작), date(최신 항목 우선), 그리고 link title 순서이다.

이를 바탕으로, 페이지나 섹션을 위로 올리고 싶다면, 페이지의 프론트 매터(front matter)에 weight 값을 설정한다.

title: My Page
weight: 10

참고:

페이지 weight는 1, 2, 3과 같은 연속된 값을 사용하기보다는 10, 20, 30과 같이 간격을 둔 값을 사용하는 것이 좋다.이렇게 하면 이후에 원하는 위치에 페이지를 삽입할 수 있다.또한 같은 디렉터리(섹션) 내에서는 각 weight 값이 서로 겹치지 않아야 한다.이는 특히 현지화된 콘텐츠에서 문서가 항상 올바르게 구성되도록 보장한다.

문서 메인 메뉴

문서 메인 메뉴는 _index.md 섹션 콘텐츠 파일의 프론트 매터에 main_menu 플래그가 설정된 docs/ 아래의 섹션들로 구성된다.

main_menu: true

링크 제목은 페이지의 linkTitle에서 가져오므로, 따라서 제목과 다르게 표시하고 싶다면, 콘텐츠 파일에서 이를 변경한다.

main_menu: true
title: Page Title
linkTitle: Title used in links

참고:

위 설정은 언어별로 각각 수행해야 한다. 메뉴에서 해당 섹션이 보이지 않는다면,Hugo에서 해당 디렉터리를 섹션으로 인식하지 못했기 때문일 수 있다.이 경우 섹션 폴더 안에 _index.md 콘텐츠 파일을 생성한다.

문서 사이드 메뉴

문서 사이드바 메뉴는 docs/ 아래에서 시작하는 현재 섹션 트리를 기반으로 구성된다.

모든 섹션과 해당 섹션에 포함된 페이지가 표시된다.

섹션이나 페이지를 목록에 표시하고 싶지 않다면, 프론트 매터에서 toc_hide 플래그를 true로 설정한다.

toc_hide: true

콘텐츠가 있는 섹션으로 이동하면, 해당 섹션 또는 페이지 (예: _index.md)가 표시된다. 그렇지 않은 경우에는 해당 섹션 안의 첫 번째 페이지가 표시된다.

문서 브라우저

문서 홈 페이지의 페이지 브라우저는 docs section 바로 아래에 위치한 모든 섹션과 페이지를 사용해 구성된다.

섹션이나 페이지를 목록에 표시하고 싶지 않다면, 프론트 매터에서 toc_hide 플래그를 true로 설정한다.

toc_hide: true

메인 메뉴

오른쪽 상단 메뉴와 푸터에 있는 사이트 링크는 페이지 조회를 통해 구성된다. 이는 해당 페이지가 실제로 존재하는지 확인하기 위함이다. 따라서, 사이트에case-studies 섹션이 존재하지 않으면, 해당 섹션으로는 링크되지 않는다.

페이지 번들

독립적인 콘텐츠 페이지(Markdown 파일) 외에도 Hugo는페이지 번들을 지원한다.

대표적인 예로 사용자 정의 Hugo 단축 코드가 있다.이는 leaf bundle로 간주된다. index.md파일을 포함한 해당 디렉터리 아래에 있는 모든 파일은 번들의 일부가 된다. 여기에는 페이지 기준 상대 링크, 처리 가능한 이미지 등도 포함된다.

en/docs/home/contribute/includes
├── example1.md
├── example2.md
├── index.md
└── podtemplate.json

또 다른 널리 사용되는 예로 includes 번들이 있다. 이 번들은 프론트 매터에 headless: true를 설정하며, 이는 자체 URL을 가지지 않는다는 의미이다. 해당 번들은 다른 페이지에서만 사용된다.

en/includes
├── default-storage-class-prereqs.md
├── index.md
├── partner-script.js
├── partner-style.css
├── task-tutorial-prereqs.md
├── user-guide-content-moved.md
└── user-guide-migration-notice.md

번들 안에 파일과 관련해 다음과 같은 중요한 사항이 있다.

번역된 번들의 경우, 누락된 비콘텐츠 파일은 상위 언어에서 상속된다. 이를 통해 중복을 방지한다.
번들에 포함된 모든 파일은 Hugo에서 Resources라고 부르는 대상이며,프론트 매터(YAML 파일 등)을 지원하지 않는 경우에도 파라미터나 제목과 같은 메타데이터를 언어별로 제공할 수 있다.페이지 리소스 메타데이터를 참고하자.
Resource의 .RelPermalink에서 얻는 값은 페이지 기준 상대 경로이다.Permalinks를 참고하자.

스타일

이 사이트의 스타일시트에 대한 SASS 소스는assets/sass에 저장되어 있으며 Hugo에 의해 자동으로 빌드된다.

다음 내용

사용자 정의 Hugo 단축 코드에 대해 알아보기.
스타일 가이드에 대해 알아보기.
콘텐츠 가이드에 대해 알아보기.