문서 스타일 개요

• 1: 새로운 주제의 문서 작성
• 2: 페이지 콘텐츠 유형

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

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

문서에 이미지 추가

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

다음 내용

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

2 - 페이지 콘텐츠 유형

쿠버네티스 문서는 여러 타입의 페이지 콘텐츠를 따른다.

• 개념
• 태스크
• 튜토리얼
• 레퍼런스

콘텐츠 섹션

각 페이지 콘텐츠 타입은 마크다운 코멘트와 HTML 헤딩(heading)으로 정의된 여러 섹션을 포함한다. heading 숏코드(shortcode)를 사용하여 페이지에 콘텐츠 헤딩을 추가할 수 있다. 코멘트와 헤딩은 페이지 콘텐츠 타입의 구조를 유지하는 데 도움이 된다.

페이지 콘텐츠 섹션을 정의하는 마크다운 코멘트 예시:

<!-- overview -->

<!-- body -->

콘텐츠 페이지에 공통적인 헤딩을 생성하려면, 헤딩 문자열과 함께 heading 숏코드를 사용한다.

헤딩 문자열 예시

• whatsnext
• prerequisites
• objectives
• cleanup
• synopsis
• seealso
• options

예를 들어, 다음 내용(whatsnext) 헤딩을 생성하려면 "whatsnext" 문자열과 함께 다음의 헤딩 숏코드를 추가한다.

## {{% heading "whatsnext" %}}

prerequisites 헤딩은 다음과 같이 선언할 수 있다.

## {{% heading "prerequisites" %}}

heading 숏코드는 하나의 문자열 파라미터를 예상한다. 헤딩 문자열 파라미터는 i18n/<lang>/<lang>.toml 파일에 정의된 변수명 앞부분과 일치한다. 예시

i18n/en/en.toml:

[whatsnext_heading]
other = "What's next"

i18n/ko/ko.toml:

[whatsnext_heading]
other = "다음 내용"

콘텐츠 타입

각 콘텐츠 타입은 관례적으로 권장되는 페이지 구조를 정의한다. 제시된 페이지 섹션을 활용하여 페이지 콘텐츠를 생성하면 된다.

개념

개념 페이지는 쿠버네티스의 특정 측면을 설명한다. 예를 들어, 개념 페이지는 쿠버네티스 디플로이먼트(Deployment) 오브젝트를 설명하고 배포, 스케일링, 업데이트된 애플리케이션에 수행하는 역할을 설명할 수 있다. 일반적으로 개념 페이지는 단계별 순서를 포함하지 않고, 대신 태스크나 튜토리얼에 대한 링크를 제공한다.

새 개념 페이지를 작성하려면, /content/ko/docs/concepts 디렉터리의 하위 디렉터리에 다음과 같은 형식을 가진 마크다운 파일을 생성한다.

개념 페이지는 세 개의 섹션으로 나뉜다.

overview와 body 섹션은 개념 페이지에 코멘트로 나타난다. heading 숏코드를 사용하여 페이지에 whatsnext 섹션을 추가할 수 있다.

각 섹션을 콘텐츠로 채우도록 한다. 다음 가이드라인을 따른다.

• H2 및 H3 헤딩으로 콘텐츠를 구성한다.
• overview의 경우, 단일 문단으로 주제의 컨텍스트를 설정한다.
• body의 경우, 개념을 설명한다.
• whatsnext의 경우, 개념에 대해 더 학습할 수 있는 주제의 불릿 리스트(최대 5개)를 제공한다.

어노테이션은 공개된 개념 페이지의 예시이다.

태스크

태스크 페이지는 보통 간단한 단계별 절차를 통해, 단일 작업을 수행하는 방법을 설명한다. 태스크 페이지는 최소한의 간결한 설명을 포함하지만, 관련 배경과 지식을 제공하기 위해서
종종 개념적인 내용에 대한 링크를 종종 제공한다.

새 태스크 페이지를 작성하려면, /content/ko/docs/tasks 디렉터리의 하위 디렉터리에 다음과 같은 특성을 가진 마크다운 파일을 생성한다.

overview, steps, discussion 섹션은 태스크 페이지에 코멘트로 나타난다. heading 숏코드를 사용하여 페이지에 prerequisites와 whatsnext 섹션을 추가할 수 있다.

각 섹션 내에 콘텐츠를 작성한다. 이때 다음 가이드라인을 사용한다.

• 최소 H2 헤딩을 사용한다(# 문자 두 개로 시작). 섹션 자체는 템플릿에 의해 자동으로 제목이 지정된다.
• overview의 경우, 전체 주제에 대한 컨텍스트를 설정하기 위해 문단을 사용한다.
• prerequisites의 경우, 가능하면 불릿 리스트를 사용한다. include 아래에 추가 전제조건을 추가하여 시작한다. 기본 전제조건에는 실행 중인 쿠버네티스 클러스터가 포함된다.
• steps의 경우, 번호 매김 리스트를 사용한다.
• discussion의 경우, 일반 콘텐츠를 사용하여 steps에 다룬 정보를 확장한다.
• whatsnext의 경우, 독자가 다음에 읽을 수 있는 최대 5개의 주제 불릿 리스트를 제공한다.

태스크 주제에 대한 공개된 예시는 HTTP 프록시를 사용하여 쿠버네티스 API에 접근이다.

튜토리얼

튜토리얼 페이지는 단일 태스크보다 큰 목표를 달성하는 방법을 보여준다. 일반적으로 튜토리얼 페이지는 여러 섹션을 가지며, 각 섹션에는 단계별 순서가 있다. 예를 들어, 튜토리얼은 쿠버네티스의 특정 기능을 설명하는 코드 샘플의 예시를 제공할 수 있다. 튜토리얼은 개괄적인 설명을 포함할 수 있지만, 심층적인 설명을 위해서는 관련 개념 주제에 링크로 연결해야 한다.

새 튜토리얼 페이지를 작성하려면, /content/ko/docs/tutorials 디렉터리의 하위 디렉터리에 다음과 같은 특성을 가진 마크다운 파일을 생성한다.

overview, objectives, lessoncontent 섹션은 튜토리얼 페이지에 코멘트로 나타난다. heading 숏코드를 사용하여 페이지에 prerequisites, cleanup, whatsnext 섹션을 추가할 수 있다.

각 섹션 내에 콘텐츠를 작성한다. 이때 다음 가이드라인을 사용하도록 한다.

• 최소 H2 헤딩을 사용한다(# 문자 두 개로 시작). 섹션 자체는 템플릿에 의해 자동으로 제목이 지정된다.
• overview의 경우, 전체 주제에 대한 컨텍스트를 설정하기 위해 문단을 사용한다.
• prerequisites의 경우, 가능하면 불릿 리스트를 사용한다. 기본적으로 포함된 것들 아래에 추가 전제조건을 추가한다.
• objectives의 경우, 불릿 리스트를 사용한다.
• lessoncontent의 경우, 적절한 경우 번호 매김 리스트와 설명 콘텐츠를 혼합하여 사용한다.
• cleanup의 경우, 태스크를 완료한 후 클러스터의 상태를 정리하는 단계를 설명하기 위해 번호 매김 리스트를 사용한다.
• whatsnext의 경우, 독자가 다음에 읽을 수 있는 최대 5개의 주제 불릿 리스트를 제공한다.

게시된 튜토리얼 주제의 예시는 디플로이먼트(Deployment)로 스테이트리스 애플리케이션 실행하기이다.

레퍼런스

컴포넌트 도구 레퍼런스 페이지는 쿠버네티스 컴포넌트 도구에 대한 설명과 플래그 옵션 출력을 보여준다. 각 페이지는 컴포넌트 도구 명령을 사용하는 스크립트에 의해서 생성된다.

도구 레퍼런스 페이지에는 여러 섹션이 포함될 수 있다.

도구 레퍼런스 페이지의 공개된 예시

• kubeadm init
• kube-apiserver
• kubectl

다음 내용

• 스타일 가이드에 대해 알아보기
• 콘텐츠 가이드에 대해 알아보기
• 콘텐츠 구성에 대해 알아보기