Markdown Formatting Guide
출처: 문서
본문
Markdown 서식 가이드
이 가이드는 OpenSearch 문서에서 사용하는 Markdown 및 Jekyll 서식 요소를 개략적으로 설명해요. 브랜드 아이덴티티, 명명 규칙, 어조와 관련해서는 스타일 가이드를 참고하세요. 문법, 문장부호, 단어 선택과 관련해서는 작성 가이드를 참고하세요. 콘텐츠 서식 규칙과 관련해서는 텍스트 서식 가이드를 참고하세요.
목차
{: .text-delta } - TOC {:toc}페이지 또는 섹션 추가
이 저장소에는 Jekyll collections(예: _api-reference 또는 _dashboards)로 구성된 Markdown 파일이 들어 있어요. 각 Markdown 파일은 웹사이트의 한 페이지에 대응해요.
특정 페이지의 콘텐츠 외에도, 각 Markdown 파일에는 다음과 같은 Jekyll front matter가 포함되어 있어요:
---
layout: default
title: Date
nav_order: 25
has_children: false
parent: Date field types
grand_parent: Supported field types
great_grand_parent: Mappings
---
콘텐츠를 재구성하거나 새 페이지를 추가하려면, 왼쪽 탐색에서 페이지 계층 구조를 정의하는 has_children, parent, grand_parent, great_grand_parent, nav_order 변수를 적절히 설정해야 해요.
페이지나 섹션을 추가할 때는 자식 페이지의 nav_order를 10의 배수로 만드세요. 예를 들어 부모 페이지가 Clients라면, 자식 페이지 Java, Python, JavaScript의 nav_order를 각각 10, 20, 30으로 지정해요. 이렇게 하면 기존 페이지 번호를 다시 매기지 않고도 자식 페이지를 추가하기가 훨씬 쉬워져요.
각 컬렉션에는 컬렉션의 인덱스 페이지에 해당하는 index.md 파일이 반드시 있어야 해요. 페이지가 컬렉션 아래에 별도로 나타나지 않도록 index.md 파일의 front matter에 nav_excluded: true를 지정하세요.
버튼
삼중 백틱으로 서식을 지정한 코드 조각에는 copy 또는 copy-curl include를 사용할 수 있어요. copy include는 코드 조각에 Copy 버튼을 추가하고, copy-curl include는 Copy 버튼과 Copy as cURL 버튼을 모두 추가해요. API 요청에는 copy-curl include를 사용하세요. API 요청이 이미 cURL 형식이라면 copy include를 사용해요.
copy include 예시
```bash
curl -XGET "localhost:9200/_tasks?actions=*search&detailed
```
{% raw %}{% include copy.html %}{% endraw %}
copy-curl include 예시
```json
PUT /sample-index1/_clone/cloned-index1
{
"aliases": {
"sample-alias1": {}
}
}
```
{% raw %}{% include copy-curl.html %}{% endraw %}
콜아웃
콜아웃은 네 가지 수준으로 사용할 수 있어요:
{: .note}파란색{: .tip }초록색{: .important}노란색{: .warning}빨간색
콜아웃 스타일을 적용하려는 단락 바로 아래에 콜아웃을 놓으세요.
예시
In case of a cluster or node failure, all PIT data is lost.
{: .note}
여러 단락이나 목록이 있는 콜아웃에는 >를 사용하세요:
> **PREREQUISITE**
>
> To use a custom vector map with GeoJSON, install these two required plugins:
> * OpenSearch Dashboards Maps [`dashboards-maps`](https://github.com/opensearch-project/dashboards-maps_) front-end plugin
> * OpenSearch [`geospatial`](https://github.com/opensearch-project/geospatial_) backend plugin
{: .note}
카드
페이지에 카드를 추가하려면 다음과 같이 front matter에 지정하세요. description, link, list는 선택 사항이에요. 상대 링크를 사용하세요. 필요하면 HTML 태그로 텍스트에 스타일을 줄 수도 있어요:
tutorial_cards:
- heading: "Getting started with semantic and hybrid search"
description: "Learn how to implement semantic and hybrid search"
link: "/vector-search/tutorials/neural-search-tutorial/"
list:
- "<b>Platform:</b> OpenSearch"
- "<b>Model:</b> Anthropic Claude"
- "<b>Deployment:</b> Amazon Bedrock"
카드가 나타나길 원하는 위치의 페이지 본문에 include를 삽입하세요:
{% raw %}{% include cards.html cards=page.tutorial_cards %}{% endraw %}
코드 블록
코드 블록을 서식 지정하는 방법은 두 가지예요:
- 단일 코드 블록: 삼중 백틱을 사용하고 코드 블록의 구문 강조 언어를 지정해요. 예를 들어 REST 요청은 다음과 같이 서식을 지정해요:
copy 및 copy as cURL 버튼 include에 대한 내용은 버튼을 참고하세요.```json PUT /hotels-index { "settings": { "index.knn": true }, "mappings": { "properties": { "location": { "type": "knn_vector", "dimension": 2, "space_type": "l2" } } } } ``` {% raw %}{% include copy-curl.html %}{% endraw %} - 탭 패널: 같은 예제를 여러 프로그래밍 언어로 제공하려면 탭 패널을 사용해요. 이 방법을 사용하면 버튼이 프로그램적으로 삽입돼요. 다음 구문을 사용하면 예제를 여러 언어로 제공할 수 있어요. 이 예제는 REST 탭과 Python 탭이 있는 탭 패널을 만들어요:
지원되는 언어는 이 yaml 파일에 정리되어 있어요.{% raw %}{% capture step1_rest %}{% endraw %} PUT /hotels-index { "settings": { "index.knn": true }, "mappings": { "properties": { "location": { "type": "knn_vector", "dimension": 2, "space_type": "l2" } } } } {% raw %}{% endcapture %}{% endraw %} {% raw %}{% capture step1_python %}{% endraw %} from opensearchpy import OpenSearch client.indices.create( index="hotels-index", body={ "settings": {"index.knn": True}, "mappings": { "properties": { "location": { "type": "knn_vector", "dimension": 2, "space_type": "l2" } } } } ) {% raw %}{% endcapture %}{% endraw %} {% raw %}{% include code-block.html rest=step1_rest python=step1_python %}{% endraw %}
접을 수 있는 블록
열린 상태의 접을 수 있는 블록을 삽입하려면 다음과 같이 <details> 요소를 사용하세요:
<details open markdown="block">
<summary>
Response
</summary>
{: .text-delta}
```json
{
"_nodes" : {
"total" : 1,
"successful" : 1,
"failed" : 0
}
}
```
</details>
닫힌 상태의 접을 수 있는 블록을 삽입하려면 open 상태를 생략하세요:
<details markdown="block">
<summary>
Response
</summary>
{: .text-delta}
```json
{
"_nodes" : {
"total" : 1,
"successful" : 1,
"failed" : 0
}
}
```
</details>
접을 수 있는 블록은 긴 응답이나 페이지 시작 부분의 목차에 유용해요.
접을 수 있는 목차를 삽입하려면 다음 마크업을 사용하세요:
<details markdown="block">
<summary>
Table of contents
</summary>
{: .text-delta }
- TOC
{:toc}
</details>
대시
하이픈에는 대시 하나, en 대시에는 두 개, em 대시에는 세 개를 사용하세요:
upper-right
10--12 nodes per cluster
There is one candidate generator available---`direct_generator`.
수평선
수평선은 텍스트 섹션을 구분할 때 사용해요. 수평선에는 공백으로 구분한 별표 세 개를 사용하세요:
## Why use OpenSearch?
* * *
이미지
이미지는 문서 웹사이트의 images 디렉터리에 넣으세요. 이미지를 참조할 때는 상대 링크를 사용해요(자세한 내용은 내부 링크 참고).
Markdown 이미지는 기본적으로 반응형으로 렌더링돼요. Markdown 이미지를 삽입하려면  구문을 사용하세요:
Markdown은 이미지의 실제 너비를 사용해 렌더링하며, 이미지의 최대 너비를 본문 패널 너비로 설정해요.
이미지 너비를 지정하고 싶다면 이미지 뒤에 Kramdown의 인라인 속성 구문을 사용하세요:
{: width="700" }
너비는 앞선 예제처럼 픽셀 수를 하드코딩해 지정하거나, 부모 너비에 대한 백분율로 지정할 수 있어요:
{: width="70%" }
이미지를 본문 패널 너비에 맞게 늘리려면 width=“100%”를 사용하세요.
고해상도 스크린샷을 찍으려면 Firefox에서 페이지를 마우스 오른쪽 버튼으로 클릭한 다음 “Take Screenshot”을 선택하세요.
이미지 테두리는 자동으로 붙으니, 이미지에 테두리를 직접 추가하지 마세요.
항상 이미지는 빈 줄을 두어 텍스트와 분리하세요:
To send a query to OpenSearch, select the query by placing the cursor anywhere in the query text. Then choose the triangle on the top right of the request or press `Ctrl/Cmd+Enter`:
이미지를 텍스트 바로 옆에 놓거나 <br>로 인위적인 줄바꿈을 넣지 마세요. 그러지 않으면 이미지가 오른쪽에 놓이고 텍스트가 이미지 아래쪽에 맞춰 정렬된 채로 렌더링될 수 있어요.
이미지가 목록 항목 아래에 오는 경우에는 새 줄에 탭을 넣어 배치하세요. 더 많은 예제는 코드 조각이나 이미지가 있는 목록을 참고하세요.
텍스트와 인라인으로 배치된 이미지
아이콘을 설명할 때는 아이콘 이름 뒤에 괄호로 묶은 인라인 이미지를 붙이세요. nomarkdown 확장과 HTML 이미지를 사용해 이미지를 텍스트와 인라인으로 삽입해요:
Choose the play icon ({::nomarkdown}<img src="{% raw %}{{site.url}}{% endraw %}{% raw %}{{site.baseurl}}{% endraw %}/images/dev-tools/play-icon.png" class="inline-icon" alt="play icon"/>{:/}) on the upper right of the request.
레이블
다음 레이블을 사용할 수 있어요:
- label-blue
- label-green
- label-purple
- label-red
- label-yellow
API가 처음 도입된 버전을 표시하려면 보라색 레이블을 사용하세요:
# Alias
**Introduced 1.0**
{: .label .label-purple }
연산에 breaking change를 도입하는 경우, 해당 breaking change의 릴리스 노트로 연결되는 링크가 담긴 레이블을 추가로 붙이세요:
## Get roles
**Introduced 1.0**
{: .label .label-purple }
[Last breaking change 2.0](https://example.com)
{: .label .label-red }
링크
문서, 섹션, 이미지에 링크를 추가하려면 [name](link) 구문을 사용하세요. 예를 들면 다음과 같아요:
## Looking for the Javadoc?
See [opensearch.org/javadocs/](https://opensearch.org/javadocs/).
섹션 링크
섹션 링크는 문서 안의 헤딩을 가리키는 링크예요. Markdown은 링크를 만들 때 헤딩을 소문자로 바꾸고, 백틱은 없애고, 공백은 하이픈으로 바꿔요:
## The `minimum_should_match` parameter
For more information, see [the `minimum_should_match` parameter](#the-minimum_should_match-parameter).
내부 링크
내부 링크는 문서 웹사이트 안의 다른 문서나 이미지를 가리키는 링크예요. 문서 웹사이트는 버전별로 관리되기 때문에 링크에 버전 번호를 하드코딩하지 마세요. 대신 메인 디렉터리를 가리키는 {% raw %}{{site.url}}{% endraw %}{% raw %}{{site.baseurl}}{% endraw %}가 포함된 상대 경로를 사용하세요:
If you need to use a field for exact-value search, map it as a [`keyword`]({% raw %}{{site.url}}{% endraw %}{% raw %}{{site.baseurl}}{% endraw %}/opensearch/supported-field-types/keyword/).
GitHub 링크
GitHub 이슈나 PR에 링크할 때는 다음 형식으로 이슈 번호나 PR 번호를 참조하세요:
For more details, see issue [#1940](https://github.com/opensearch-project/opensearch/issues/1940).
목록
Markdown은 순서 없는 목록, 순서 있는 목록, 중첩 목록, 그리고 코드 조각이나 이미지가 포함된 목록을 지원해요.
순서 없는 목록
순서 없는 목록에는 별표나 대시를 사용하세요:
* One
* Two
또는
- One
- Two
대시를 사용한 목록은 항목들이 세로 방향으로 더 촘촘하게 렌더링되고, 별표를 사용한 목록은 줄 사이 간격이 더 넓어요.
별표와 대시를 섞어 쓰지 마세요.
순서 있는 목록
순서 있는 목록에는 모두 1을 사용하세요:
1. One
1. Two
Jekyll이 항목에 자동으로 올바른 번호를 매겨 주기 때문에, 번호를 다시 매길 필요 없이 항목을 훨씬 쉽게 삽입하고 삭제할 수 있어요.
목록 중간에 단락이 끼어 있으면 단락 뒤에서 목록이 1부터 다시 시작해요. 단락 뒤에서 목록을 이어가고 싶다면 counter-reset: none을 사용하세요:
1. One
Paragraph that breaks the numbering
{:style="counter-reset: none"}
1. Two
중첩 목록
목록을 중첩하려면 탭을 사용하세요:
1. Parent 1
- Child 1
- Child 2
- Grandchild 1
Markdown은 번호 목록이 숫자와 문자를 알아서 조합하도록 자동 조정해 주므로, 중첩된 번호 목록에서도 항상 1을 사용하면 돼요.
코드 조각이나 이미지가 있는 목록
목록 안에서 이미지나 코드 조각의 위치를 잡아야 한다면, 탭을 사용해 이미지나 코드 조각이 해당 목록 항목의 일부임을 Markdown에 알려 주세요.
코드 조각이 있는 예시
1. Run the demo batch script.
There are two ways of running the batch script:
1. Run the batch script using the Windows UI:
1. Navigate to the top directory of your OpenSearch installation and open the `opensearch-{% raw %}{{site.opensearch_version}}{% endraw %}` folder.
1. Run the batch script by double-clicking the `opensearch-windows-install.bat` file. This opens a command prompt with an OpenSearch instance running.
1. Run the batch script from Command prompt or Powershell:
1. Open Command Prompt by entering `cmd`, or Powershell by entering `powershell`, in the search box next to ****Start**** on the taskbar.
1. Change to the top directory of your OpenSearch installation.
```bat
cd \path\to\opensearch-{% raw %}{{site.opensearch_version}}{% endraw %}
```
1. Run the batch script.
```bat
.\opensearch-windows-install.bat
```
이미지가 있는 예시
1. To begin, select the rule in the **Rule name** column. The rule details pane opens, as shown in the following image.
{: width="50%"}
1. Select the **Duplicate** button in the upper-right corner of the pane. The **Duplicate rule** window opens in Visual Editor view, and all of the fields are automatically populated with the rule's details. Details are also populated in YAML Editor view, as shown in the following image.
{: width="50%"}
수학식
페이지에 수학식을 추가하려면 페이지의 front matter에 has_math: true를 추가하세요. 그런 다음 아래 예제처럼 LaTeX 수학식을 HTML 태그로 감싸서 나머지 Markdown 콘텐츠와 함께 넣어 주세요:
## Math
Some Markdown paragraph. Here's a formula:
<p>
When \(a \ne 0\), there are two solutions to \(ax^2 + bx + c = 0\) and they are
\[x = {-b \pm \sqrt{b^2-4ac} \over 2a}.\]
</p>
And back to Markdown.
또는 디스플레이 수학식이든 인라인 수학식이든 이중 달러 기호($$)를 써서 Markdown에서 바로 작성할 수도 있어요:
The probability of selecting pair $$i$$ is proportional to $$1 \over i^\alpha$$.
단계
단계를 삽입하려면 다음과 같이 front matter에 지정하세요. 단계에는 자동으로 번호가 매겨져요. 상대 링크를 사용하고, description과 link는 선택 사항이에요:
steps:
- heading: "Create an OpenSearch index"
description: "Create an OpenSearch index to store your embeddings."
link: "/vector-search/creating-vector-index/#storing-raw-vectors-or-embeddings-generated-outside-of-opensearch"
- heading: "Ingest embeddings"
description: "Ingest your embeddings into the index."
link: "/vector-search/ingesting-data/#raw-vector-ingestion"
단계가 나타나길 원하는 위치의 페이지 본문에 include를 삽입하세요:
{% raw %}{% include list.html list_items=page.steps%}{% endraw %}
표
Markdown 표의 열은 자동으로 크기가 조정되므로, 서식을 지정할 때 대시 개수를 달리할 필요가 없어요.
예시
Header 1 | Header 2
:--- | :---
Body 1 | Body 2, which is extremely lengthy, but there is no need to specify its width.
표 안에서 줄을 바꾸려면 <br>을 사용하세요:
Header 1 | Header 2
:--- | :---
Body 1 | Body paragraph 1 <br> Body paragraph 2
표 안에서 목록을 쓰려면 <br>과 -를 사용하세요:
Header 1 | Header 2
:--- | :---
Body 1 | List:<br>- One<br>- Two
표 셀 안에서는 로 공백 하나,  로 공백 두 개,  로 공백 네 개를 삽입할 수도 있어요.
실제 불릿 포인트가 달린 목록이 필요하면 불릿 포인트 HTML 코드를 사용하세요:
Header 1 | Header 2
:--- | :---
Body 1 | List:<br> • One<br> • Two
텍스트 스타일
텍스트는 다음과 같은 방법으로 스타일을 지정할 수 있어요:
**bold**_italic_또는*italic*
코드 예제 사용 방법과 코드 폰트를 언제 써야 하는지는 코드 예제를 참고하세요.
중괄호 안의 변수
중괄호로 묶인 변수를 제대로 표시하려면 {{ "{% raw " }}%}{{ "{% endraw " }}%} 태그로 중괄호를 이스케이프하세요:
"message_template": {
"source": "the index is {{ "{% raw " }}%}{% raw %}{{ctx.index}}{% endraw %}{{ "{% endraw " }}%}"
}
변수 ctx.index는 이중 중괄호로 묶여 렌더링돼요:
"message_template": {
"source": "the index is {% raw %}{{ctx.index}}{% endraw %}"
}
동영상
동영상을 삽입하려면 다음과 비슷한 YouTube 플레이어 include를 추가하세요:
{% raw %}{% include youtube-player.html id='_g46WiGPhFs' %}{% endraw %}
id 변수는 URL 끝에 있는 YouTube 동영상 ID를 가리킨다는 점에 유의하세요. 예를 들어 URL https://youtu.be/_g46WiGPhFs에 있는 YouTube 동영상의 ID는 _g46WiGPhFs예요. ID는 반드시 작은따옴표로 감싸야 해요.