기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 이 가이드에 기여
누구나 모범 사례 가이드에 기여할 수 있습니다. EKS 모범 사례 가이드는 GitHub에서 AsciiDoc 형식으로 작성되었습니다.
## 기존 기여자에 대한 요약
+ VS Code[https://github.com/aws/aws-eks-best-practices/blob/master/bpg-docs.code-workspace](https://github.com/aws/aws-eks-best-practices/blob/master/bpg-docs.code-workspace)를 사용하여를 열어 AsciiDoc 확장을 자동으로 설치합니다.
+ Visual Studio Marketplace의 [AsciiDoc 확장](https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode)에 대해 자세히 알아보세요.
+ AWS Docs 웹 사이트의 소스 파일은에 저장됩니다. [https://github.com/aws/aws-eks-best-practices/tree/master/latest/bpg](https://github.com/aws/aws-eks-best-practices/tree/master/latest/bpg)
+ 구문은 마크다운과 매우 유사합니다.
+ AsciiDoctor 문서의 [구문 참조](https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/)를 검토합니다.
+ 문서 플랫폼은 만 배포합니다`latest/bpg/images`. 각 가이드 섹션에는이 디렉터리로 돌아가는 심볼 링크가 있습니다. 예를 들어는를 `latest/bpg/networking/images` 가리킵니다`latest/bpg/images`.
## 로컬 편집 환경 설정
가이드를 자주 편집하려는 경우 로컬 편집 환경을 설정합니다.
### 리포지토리 포크 및 복제
`git`, `github`및 텍스트 편집기에 익숙해야 합니다. `git` 및 시작하기에 대한 자세한 내용은 [ GitHub 문서의 GitHub 계정 시작하기](https://docs.github.com/en/get-started/onboarding/getting-started-with-your-github-account)를 `github`참조하세요. GitHub
1. [GitHub에서 EKS 모범 사례 가이드를](https://github.com/aws/aws-eks-best-practices) 확인하세요.
1. 프로젝트 리포지토리의 포크를 생성합니다. GitHub 문서에서 [리포지토리를 포크하는](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#forking-a-repository) 방법을 알아봅니다.
1. 프로젝트 리포지토리의 포크를 복제합니다. [포크된 리포지토리를 복제](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#cloning-your-forked-repository)하는 방법을 알아봅니다.
### VS Code Workspace 열기
AWS는 Microsoft의 Visual Studio 코드를 사용하여 가이드를 편집할 것을 권장합니다. VS Code에 대한 자세한 내용은 [Visual Studio Code 설명서의 Visual Studio Code 다운로드](https://code.visualstudio.com/download) [및 Visual Studio Code 시작하기](https://code.visualstudio.com/docs/getstarted/getting-started)를 참조하세요.
1. VS Code를 엽니다.
1. 복제된 리포지토리에서 `bpg-docs.code-workspace` 파일을 엽니다.
1. 이 워크스페이스를 처음 여는 경우 프롬프트를 수락하여 AsciiDoc 확장을 설치합니다. 이 확장은 AsciiDoc 파일의 구문을 확인하고 라이브 미리 보기를 생성합니다.
1. `latest/bpg` 디렉터리로 이동합니다. 이 디렉터리에는 AWS 설명서 사이트에 배포되는 소스 파일이 들어 있습니다. 소스 파일은 "보안" 또는 "네트워크"와 같은 가이드 섹션별로 구성됩니다.
### 파일 편집
1. 편집기에서 파일을 엽니다.
+ AsciiDoc 구문을 보고 제목, 링크 및 목록을 생성하는 방법을 알아봅니다.
+ 마크다운 구문을 사용하여 텍스트, 목록 및 제목의 형식을 지정할 수 있습니다. 마크다운 구문을 사용하여 링크를 생성할 수 없습니다.
1. 페이지의 라이브 미리 보기를 엽니다.
+ 먼저 `ctrl-k` 또는 `cmd-k` (키보드에 따라 다름)를 누릅니다. 둘째,를 누릅니다`v`. 그러면 분할 보기에서 미리 보기가 열립니다.
AWS는 기능 브랜치를 사용하여 변경 사항을 구성할 것을 제안합니다. git을 사용하여 브랜치를 생성하는 방법을 알아봅니다.
### 풀 요청 제출
GitHub 웹 사이트 또는 GitHub cli에서 풀 요청을 생성할 수 있습니다.
GitHub 웹 사이트를 사용하여 [포크에서 풀 요청을 생성하는](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) 방법을 알아봅니다.
GitHub cli[를 사용하여 풀 요청을 생성하는](https://cli.github.com/manual/gh_pr_create) 방법을 알아봅니다.
## github.dev 웹 기반 편집기 사용
`github.dev` 웹 기반 편집기는 VS Code를 기반으로 합니다. 이는 설정 없이 여러 파일을 편집하고 콘텐츠를 미리 볼 수 있는 좋은 방법입니다.
AsciiDoc 확장을 지원합니다. GUI를 사용하여 git 작업을 수행할 수 있습니다. 웹 기반 편집기에는 명령을 실행하기 위한 셸 또는 터미널이 없습니다.
GitHub 계정이 있어야 합니다. 필요한 경우 로그인하라는 메시지가 표시됩니다.
[🚀 GitHub 웹 기반 편집기를 시작합니다.](https://github.dev/aws/aws-eks-best-practices/blob/master/bpg-docs.code-workspace?workspace=true)
## 단일 페이지 편집
GitHub를 사용하여 개별 페이지를 빠르게 업데이트할 수 있습니다. 각 페이지에는 하단에 “📝GitHub에서이 페이지 편집” 링크가 있습니다.
1. 이 가이드에서 편집하려는 페이지로 이동합니다.
1. 하단의 "GitHub에서이 페이지 편집" 링크를 클릭합니다.
1. GitHub 파일 뷰어의 오른쪽 상단에 있는 연필 편집 아이콘을 클릭하거나 `e`
1. 파일 편집
1. "변경 사항 커밋... " 버튼을 사용하여 변경 사항을 제출합니다. 이 버튼은 GitHub 풀 요청을 생성합니다. 가이드 유지 관리자는이 풀 요청을 검토합니다. 검토자가 풀 요청을 승인하거나 변경을 요청합니다.
## 페이지 ID 보기 및 설정
이 페이지에서는 페이지 ID를 보고 설정하는 방법을 설명합니다.
페이지 ID는 설명서 사이트의 각 페이지를 식별하는 고유한 문자열입니다. 특정 페이지에 있을 때 브라우저의 주소 표시줄에서 페이지 ID를 볼 수 있습니다. 페이지 ID는 URL, 파일 이름 및 상호 참조 링크를 생성하는 데 사용됩니다.
예를 들어이 페이지를 보는 경우 브라우저 주소 표시줄의 URL은 다음과 같습니다.
```
https://docs.aws.amazon.com/view-set-page-id.html
```
URL의 마지막 부분(`view-set-page-id`)은 페이지 ID입니다.
### 페이지 ID 설정
새 페이지를 생성할 때 소스 파일에서 페이지 ID를 설정해야 합니다. 페이지 ID는 페이지 콘텐츠를 설명하는 간결한 하이픈 문자열이어야 합니다.
1. 텍스트 편집기에서 새 페이지의 소스 파일을 엽니다.
1. 파일 상단에 다음 줄을 추가합니다. 첫 번째 제목 위에 있어야 합니다.
```
[#my-new-page]
```
를 새 페이지의 페이지 ID`my-new-page`로 바꿉니다.
1. 파일을 저장합니다.
**참고**
페이지 IDs 전체 설명서 사이트에서 고유해야 합니다. 기존 페이지 ID를 사용하려고 하면 빌드 오류가 발생합니다.
## 새 페이지 생성
새 페이지를 생성하고 가이드 목차를 업데이트하는 방법을 알아봅니다.
### 페이지 메타데이터 생성
1. 페이지 제목과 페이지 짧은 제목을 결정합니다. 페이지 짧은 제목은 선택 사항이지만 페이지 제목이 몇 단어 이상인 경우 권장됩니다.
1. 페이지의 ID를 확인합니다. EKS 모범 사례 가이드 내에서 고유해야 합니다. 규칙은 소문자를 모두 사용하고 로 단어를 구분하는 것입니다`-`.
1. 필요한 경우 폴더에 새 asciidoc 파일을 생성하고 파일에 다음 텍스트를 추가합니다.
**Example**
[."topic"] [\#] = :info\_titleabbrev:
예:
**Example**
[."topic"] [\#scalability] = EKS Scalability 모범 사례: info\_titleabbrev: Scalability
### 목차에 추가
1. 목차에서 상위 페이지의 파일을 엽니다. 새로운 최상위 가이드 섹션의 경우 상위 파일은 입니다`book.adoc`.
1. 상위 파일 하단에서 다음 지시문을 업데이트하고 삽입합니다.
**Example**
포함::[leveloffset=\+1]
예를 들어,
**Example**
include::dataplane.adoc[leveloffset=\+1]
## 이미지 삽입
1. 편집하려는 페이지의 이미지 접두사를 찾습니다. 파일 제목의 `:imagesdir:` 속성을 검토합니다. 예를 들어, ``:imagesdir: images/reliability/`
1. 와 같이이 경로에 이미지를 배치합니다. `latest/bpg/images/reliability`
1. 이미지에 적합한 alt-text를 결정합니다. 이미지에 대한 간략한 설명을 작성합니다. 예를 들어 "3개의 가용 영역이 있는 VPC의 다이어그램"은 적절한 alt-text입니다.
1. 다음 예제를 alt-text 및 이미지 파일 이름으로 업데이트합니다. 원하는 위치에를 삽입합니다.
**Example**
image::[]
예:
**Example**
image::eks-data-plane-connectivity.jpeg[네트워크 다이어그램]
## Vale을 사용하여 스타일 확인
1. [Vale CLI를 설치합니다.](https://vale.sh/docs/vale-cli/installation/)
1. `vale sync` 실행
1. Visual Studio Marketplace에서 [Vale 확장](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode)을 설치합니다.
1. VS Code를 다시 시작하고 AsciiDoc 파일을 엽니다.
1. VS 코드는 문제가 있는 텍스트를 강조 표시합니다. VS Code 문서에서 [오류 및 경고](https://code.visualstudio.com/docs/editor/editingevolved#_errors-warnings)를 사용하는 방법을 알아봅니다.
## 로컬 미리 보기 빌드
1. `brew` Linux 또는 MacOS에서를 사용하여 `asciidoctor` 도구 설치
+ [AsciiDoctor 문서에 asciidoctor cli를 설치하는](https://docs.asciidoctor.org/asciidoctor/latest/install/) 방법을 알아봅니다. AsciiDoctor
+ [brew 패키지 관리자를 설치하는](https://brew.sh/index.html) 방법을 알아봅니다.
1. 터미널을 열고 로 이동합니다. `latest/bpg/`
1. `asciidoctor book.adoc` 실행
+ 구문 경고 및 오류 검토
1. `book.html` 출력 파일을 엽니다.
+ MacOS에서는를 실행`open book.html`하여 기본 브라우저에서 미리 보기를 열 수 있습니다.
## AsciiDoc 치트 시트
### 기본 형식 지정
```
*bold text*
_italic text_
`monospace text`
```
### 헤더
```
= Document Title (Header 1)
== Header 2
=== Header 3
==== Header 4
===== Header 5
====== Header 6
```
### Lists
정렬되지 않은 목록:
```
- Item 1
- Item 2
-- Subitem 2.1
-- Subitem 2.2
- Item 3
```
정렬된 목록:
```
. First item
. Second item
.. Subitem 2.1
.. Subitem 2.2
. Third item
```
### 링크
```
External link: https://example.com[Link text]
Internal link: <>
Internal link: xref:page-id[Link text]
```
### 이미지
```
image::image-file.jpg[Alt text]
```
### 코드 블록
```
[source,python]
----
def hello_world():
print("Hello, World!")
----
```
### 테이블
[기본 테이블을 빌드하는 방법을 알아봅니다.](https://docs.asciidoctor.org/asciidoc/latest/tables/build-a-basic-table/)
```
[cols="1,1"]
|===
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 1, row 3
|Cell in column 2, row 3
|===
```
### 주의 문구
```
NOTE: This is a note admonition.
WARNING: This is a warning admonition.
TIP: This is a tip admonition.
IMPORTANT: This is an important admonition.
CAUTION: This is a caution admonition.
```
미리 보기:
**참고**
참고에 관한 주의 문구입니다.
### 포함 파일
```
include::filename.adoc[]
```