--- title: 새로운 주제의 문서 작성 content_template: templates/task weight: 20 --- {{% capture overview %}} 이 페이지는 쿠버네티스 문서에서 새로운 주제를 생성하는 방법을 보여준다. {{% /capture %}} {{% capture prerequisites %}} [기여 시작하기](/docs/contribute/start/)에 설명된 대로 쿠버네티스 문서 저장소의 포크(fork)를 생성하자. {{% /capture %}} {{% capture steps %}} ## 페이지 타입 선택 새로운 주제 작성을 준비할 때는, 콘텐츠에 가장 적합한 페이지 타입을 고려하자. {{< table caption = "페이지 타입 선택 지침" >}} 타입 | 설명 :--- | :---------- 개념 | 개념 페이지는 쿠버네티스의 일부 측면을 설명한다. 예를 들어 개념 페이지는 쿠버네티스 디플로이먼트 오브젝트를 설명하고 배치, 확장 및 업데이트되는 동안 애플리케이션으로서 수행하는 역할을 설명할 수 있다. 일반적으로 개념 페이지는 일련의 단계가 포함되지 않지만 대신 태스크나 튜토리얼에 대한 링크를 제공한다. 개념 문서의 예로서 노드를 참조하자. 태스크 | 태스크 페이지는 단일 작업을 수행하는 방법을 보여준다. 아이디어는 독자가 페이지를 읽을 때 실제로 수행할 수 있는 일련의 단계를 제공하는 것이다. 태스크 페이지는 한 영역에 집중되어 있으면 짧거나 길 수 있다. 태스크 페이지에서 수행할 단계와 간단한 설명을 혼합하는 것은 괜찮지만, 긴 설명을 제공해야 하는 경우에는 개념 문서에서 수행해야 한다. 관련 태스크와 개념 문서는 서로 연결되어야 한다. 짧은 태스크 페이지의 예제는 저장소에 볼륨을 사용하도록 파드 구성을 참조하자. 더 긴 태스크 페이지의 예제는 활동성 및 준비성 프로브 구성을 참조하자. 튜토리얼 | 튜토리얼 페이지는 여러 쿠버네티스의 특징들을 하나로 묶어서 목적을 달성하는 방법을 보여준다. 튜토리얼은 독자들이 페이지를 읽을 때 실제로 할 수 있는 몇 가지 단계의 순서를 제공한다. 또는 관련 코드 일부에 대한 설명을 제공할 수도 있다. 예를 들어 튜토리얼은 코드 샘플의 연습을 제공할 수 있다. 튜토리얼에는 쿠버네티스의 특징에 대한 간략한 설명이 포함될 수 있지만 개별 기능에 대한 자세한 설명은 관련 개념 문서과 연결지어야 한다. {{< /table >}} 새 페이지에 대한 템플릿을 사용하자. 각 페이지 타입에 있는 [템플릿](/docs/contribute/style/page-templates/) 은 문서를 작성할 때 사용할 수 있다. 템플릿을 사용하면 지정된 타입의 문서 간에 일관성을 보장할 수 있다. ## 제목과 파일 이름 선택 검색 엔진에서 찾을 키워드가 있는 제목을 선택하자. 제목에 있는 단어를 하이픈으로 구분하여 사용하는 파일 이름을 만들자. 예를 들어 [HTTP 프록시를 사용하여 쿠버네티스 API에 접근](/docs/tasks/access-kubernetes-api/http-proxy-access-api/) 이라는 제목의 문서는 `http-proxy-access-api.md`라는 이름의 파일을 가진다. "쿠버네티스"가 이미 해당 주제의 URL에 있기 때문에 파일 이름에 "쿠버네티스" 를 넣을 필요가 없다. 예를 들면 다음과 같다. /docs/tasks/access-kubernetes-api/http-proxy-access-api/ ## 전문에 항목 제목 추가 문서에서 [전문](https://gohugo.io/content-management/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`에는 템플릿이 필요없다. 그것은 하위 디렉토리의 항목에 대한 개요 내용을 포함할 수 있다. 디렉토리의 다른 파일들은 기본적으로 알파벳순으로 정렬된다. 이것은 거의 최적의 순서가 아니다. 하위 디렉토리에서 항목의 상대적 정렬을 제어하려면 `가중치:` 전문의 키를 정수로 설정하자. 일반적으로 우리는 나중에 항목을 추가하기 위해 10의 배수를 사용한다. 예를 들어 가중치가 `10`인 항목은 가중치가 `20`인 항목보다 우선한다. ## 문서에 코드 포함 문서에 코드를 포함시키려면 마크다운 코드 블록 구문을 사용하여 파일에 코드를 직접 삽입하자. 다음 경우에 권장된다. (전체 목록은 아님) - 이 코드는 `kubectl get deploy mydeployment -o json | jq '.status'`와 같은 명령어의 출력을 보여준다. - 이 코드는 시도해보기에 적절하지 않다. 예를 들어 특정 [FlexVolume](/docs/concepts/storage/volumes#flexvolume) 구현에 따라 파드를 만들기 위해 YAML 파일을 포함할 수 있다. - 이 코드의 목적은 더 큰 파일의 일부를 강조하는 것이기 때문에 불완전한 예제다. 예를 들어 몇 가지 이유로 [PodSecurityPolicy](/docs/tasks/administer-cluster/sysctl-cluster/#podsecuritypolicy) 를 사용자 정의 방법을 설명할 때 문서 파일에서 직접 짧은 요약 정보를 제공할 수 있다. - 이 코드는 사용자가 다른 이유로 시도하기 위한 것이 아니다. 예를 들어 `kubectl edit` 명령을 사용하여 리소스에 새 속성을 추가하는 방법을 설명할 때 추가할 만한 속성을 포함하는 간단한 예를 제공할 수 있다. ## 다른 파일의 코드 포함 문서에 코드를 포함시키는 또 다른 방법은 새로운 완전한 샘플 파일 (또는 샘플 파일 그룹)을 만든 다음 문서의 샘플을 참조하는 것이다. 일반적이고 재사용 가능하며 독자가 스스로 실행해 볼 수 있도록 하는 샘플 YAML 파일을 포함시키려면 이 방법을 사용하자. YAML 파일과 같은 새로운 독립형 샘플 파일을 추가할 때 `/examples/` 의 하위 디렉토리 중 하나에 코드를 배치하자. 여기서 ``은 주제에 관한 언어이다. 문서 파일에서 `codenew` 단축 코드(shortcode)를 사용하자. 
{{< codenew file="<RELPATH>/my-example-yaml>" >}}
여기서 `` 는 `examples` 디렉토리와 관련하여 포함될 파일의 경로이다. 다음 Hugo 단축 코드(shortcode)는 `/content/en/examples/pods/storage/gce-volume.yaml` 에 있는 YAML 파일을 참조한다. ```none {{}} ``` {{< note >}} 위의 예와 같은 원시 Hugo 단축 코드(shortcode)를 표시하고 Hugo가 해석하지 못하게 하려면 `<` 문자 바로 다음과 `>` 문자 앞에 C 스타일 주석을 사용하자. 그 예로서 이 페이지의 코드를 확인하자. {{< /note >}} ## 구성 파일에서 API 오브젝트를 작성하는 방법 표시 구성 파일을 기반으로 API 오브젝트를 생성하는 방법을 보여주려면 `/examples` 아래의 하위 디렉토리 중 하나에 구성 파일을 배치하자. 문서에서 이 명령을 띄워보자. ``` kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml ``` {{< note >}} `/examples` 디렉토리에 새 YAMl 파일을 추가할 때 파일이 `/examples_test.go` 파일에도 포함되어 있는지 확인하자. 웹 사이트의 Travis CI 는 PR이 제출될 때 이 예제를 자동으로 실행하여 모든 예제가 테스트를 통과하도록 한다. {{< /note >}} 이 기술을 사용하는 문서의 예로 [단일 인스턴스 스테이트풀 어플리케이션 실행](/docs/tutorials/stateful-application/run-stateful-application/)을 참조하자. ## 문서에 이미지 추가 이미지 파일을 `/images` 디렉토리에 넣는다. 기본 이미지 형식은 SVG 이다. {{% /capture %}} {{% capture whatsnext %}} * [페이지 템플릿 사용](/docs/home/contribute/page-templates/)에 대해 알아보기. * [변경 사항 준비](/docs/home/contribute/stage-documentation-changes/)에 대해 알아보기. * [풀 리퀘스트 작성](/docs/home/contribute/create-pull-request/)에 대해 알아보기. {{% /capture %}}