AsciiDoc

Tier: Free, Premium, Ultimate Offering: GitLab.com, 자체관리, GitLab Dedicated

GitLab은 AsciiDoc 콘텐츠를 HTML5로 변환하기 위해 Asciidoctor gem을 사용합니다. AsciiDoc 레퍼런스의 전체 내용은 Asciidoctor 사용자 매뉴얼을 참조하십시오.

다음 영역에서 AsciiDoc을 사용할 수 있습니다:

  • 위키 페이지
  • 리포지터리 내부의 AsciiDoc 문서(.adoc 또는 .asciidoc)

구문

가장 일반적으로 사용되는 AsciiDoc 구문에 대한 간략한 참조입니다. AsciiDoc 구문의 전체 문서는 https://asciidoctor.org/docs/에서 찾을 수 있습니다.

단락 

일반 단락.
줄 바꿈은 보존되지 않습니다.

//로 시작하는 주석은 건너뜁니다: 

// 이것은 주석입니다

공백줄은 단락을 구분합니다.

[%hardbreaks] 옵션이 있는 단락은 줄 바꿈을 보존합니다: 

[%hardbreaks]
이 단락에는 `hardbreaks` 옵션이 있습니다.
이제 줄 바꿈이 보존되는지 주목하세요.

들여쓰기된(서식이 있는) 단락은 텍스트 서식을 비활성화하고, 공백 및 줄 바꿈을 보존하며 고정폭 글꼴로 표시됩니다: 

한 칸의 공백으로 들여쓴 이 서식이 있는 단락.
결과적으로 *텍스트 서식*, 공백, 줄 바꿈이 보존됩니다.

안내 단락은 독자의 주의를 끕니다:

  • NOTE: 이것은 간단한 참조입니다. 전체 문서는 https://asciidoctor.org/docs/에서 읽으세요.
  • TIP: 디렉터리은 들여쓸 수 있습니다. 선행하는 공백은 중요하지 않습니다.

텍스트 서식

제한된(단어 경계에 적용됨) 

*강조된 중요성*(혹은 볼드)
_강조된 강조_(혹은 이탤릭)
`단일 고정폭` (혹은 타자 글꼴 텍스트)
"`이중`" 및 '`단일`' 타이포그래피용 따옴표
+치환 사항이 비활성화된 텍스트+ (치환 비활성화)
`+서식이 없는 텍스트+` (치환 비활성화가 적용된 고정폭)

제한되지 않은(어디든 적용됨) 

**C**reate+**R**ead+**U**pdate+**D**elete
fan__freakin__tastic
``mono``culture

치환 

A long time ago in a galaxy far, far away...
(C) 1976 Arty Artisan
I believe I shall--no, actually I won't.

매크로 

// 여기서 c=specialchars, q=quotes, a=attributes, r=replacements, m=macros, p=post_replacements
유럽 아이콘:flag[role=blue]은 파랗고 아이콘:circle-o[role=yellow]으로 배열된 특수문자를 포함합니다.
`pass:[->]` 연산자는 종종 스탭비 람다로 불립니다.
AsciiDoc에서 `pass:[++]`은 강한, 따라서 pass:c,a,r[C++ => C{pp}]로 재작성할 수 있습니다.
// 문서 헤더에 `:stem:`을 추가하여 stem 지원을 활성화합니다
stem:[sqrt(4) = 2]

속성

사용자 정의 속성 

// 문서 헤더에서 속성을 정의합니다
:name: value

:url-gem: https://rubygems.org/gems/asciidoctor

Asciidoctor {asciidoctor-version}을 {url-gem}에서 다운로드하여 설치할 수 있습니다.
C{pp}는 필요하지 않으며 루비만 필요합니다.
중괄호로 둘러싼 단어를 출력하려면 첫 글자에 백슬래시를 사용하세요, 예를 들어 \{name}.

환경 속성

GitLab은 다음 환경 속성을 설정합니다:

속성 설명
docname 소스 문서의 루트 이름 (선행 경로 또는 파일 확장자 없음).
outfilesuffix 백엔드 출력에 해당하는 파일 확장자 (inter-document 교참 참조를 위해 기본적으로 .adoc로 설정됨).

링크 

https://example.org/page[웹페이지]
link:../path/to/file.txt[로컬 파일]
xref:document.adoc[동료 문서]
mailto:hello@example.org[인사 이메일!]

앵커 

[[idname,참조 텍스트]]
// 또는 일반 블록 속성으로 작성된 `[#idname,reftext=참조 텍스트]`
앵커(또는 ID)와 참조 텍스트가 있는 단락.

<<idname>> 또는 <<idname,내부 링크의 선택적 텍스트>>를 참고하세요.

xref:document.adoc#idname[다른 문서의 앵커로 이동합니다].

이 단락에는 각주가 있습니다.footnote:[이것은 각주의 텍스트입니다.]

디렉터리

순서 없는 디렉터리 

* 1단계
** 2단계
*** 3단계
**** 4단계
***** 5단계
* 1단계로 돌아가기
+
열린 블록으로 묶은 디렉터리 항목에 블록이나 단락을 첨부하세요.

몇몇 저자
[circle]
- 엡가 알렌 포
- 셰리 S. 테퍼
- 빌 브라이슨

순서 있는 디렉터리 

. 단계 1
. 단계 2
.. 단계 2a
.. 단계 2b
. 단계 3

로마 숫자를 기억하십니까?
[upperroman]
. 하나
. 둘
. 셋

체크리스트 

* [x] 체크됨
* [ ] 체크 안됨

콜아웃 

// 문서 헤더에 `:icons: font`를 추가하여 콜아웃 버블을 활성화합니다
[,루비]
----
puts '안녕, 세상!' # <1>
----
<1> 콘솔에 `안녕, 세상!`을 출력합니다.

설명 

첫 번째 용어:: 첫 번째 용어의 설명
두 번째 용어::
두 번째 용어의 설명

문서 구조

헤더 

= 문서 제목
작성자 이름 <author@example.org>
v1.0, 2019-01-01

섹션 

= 문서 제목 (레벨 0)
== 레벨 1
=== 레벨 2
==== 레벨 3
===== 레벨 4
====== 레벨 5
== 1단계로 돌아가기

포함

note
AsciiDoc로 생성된 위키 페이지는 확장명 .asciidoc로 저장됩니다. AsciiDoc 위키 페이지를 처리할 때 .adoc에서 .asciidoc로 파일명을 변경하세요.
include::basics.adoc[]

시스템 성능을 보장하고 악의적인 문서가 문제를 일으키는 것을 방지하기 위해, GitLab은 한 문서에서 처리되는 포함 지시문의 최대 한도를 강제합니다. 기본적으로 문서당 최대 32개의 포함 지시문이 설정되며, 이는 추이적 의존성을 포함합니다. 처리되는 포함 지시문의 수를 사용자 정의하려면 애플리케이션 설정 API에서 asciidoc_max_includes 애플리케이션 설정을 변경하십시오.

note
asciidoc_max_includes의 현재 최대 허용 값은 64입니다. 이 값이 너무 높으면 어떤 상황에서는 성능 문제가 발생할 수 있습니다.

별도의 페이지에서 또는 외부 URL에서 포함을 사용하려면, 애플리케이션 설정에서 allow-uri-read 기능을 활성화하십시오. 

// URI에서 내용을 읽을 수 있도록 `allow-uri-read` 애플리케이션 설정을 true로 정의합니다
include::https://example.org/installation.adoc[]

블록 

--
open - 일반 목적의 콘텐츠 래퍼; 디렉터리 항목에 첨부할 내용을 둘러싸는 데 유용함
--

// 인식된 유형으로는 CAUTION, IMPORTANT, NOTE, TIP, 그리고 WARNING이 포함됨
// 문서 머릿글에 `:icons: font`을 설정하여 주의 아이콘을 활성화함으로써 주의 아이콘을 활성화함
[NOTE]
====
admonition - 팁에서 경고까지 심각성이 다양한 독자 안내 사항
====

====
example - 문서화된 개념의 데모
====

.Toggle Me
[%collapsible]
====
collapsible - 제목을 클릭하여 이 세부 정보를 공개하는 기능
====

****
sidebar - 본문 콘텐츠와 독립적으로 읽을 수 있는 보조 콘텐츠
****

....
literal - 프로그램 출력을 특징으로 하는 전시물
....

----
listing - 프로그램 입력, 소스 코드 또는 파일 내용을 특징으로 하는 전시물
----

[,language]
----
source - (색상이 지정된) 구문 강조로 꾸며진 디렉터리
----

\```language
fenced code - 소스 블록의 약식 구문
\```

[,attribution,citetitle]
____
quote - 인용문 또는 발췌문; 소스 제목과의 어트리뷰션은 선택 사항
____

[verse,attribution,citetitle]
____
verse - 종종 시인문의 발췌; 소스 제목과의 어트리뷰션은 선택 사항
____

++++
pass - 출력 문서에 직접 전달되는 콘텐츠; 종종 로우 HTML임
++++

// 문서 머릿글에 `:stem:`을 추가하여 STEM(과학, 기술, 공학 및 수학) 지원을 활성화함
[stem]
++++
x = y^2
++++

////
comment - 출력 문서에 포함되지 않는 콘텐츠
////

테이블 

.Table Attributes
[cols=>1h;2d,width=50%,frame=topbot]
|===
| 속성 이름 | 값

| options
| header,footer,autowidth

| cols
| colspec[;colspec;...]

| grid
| all \| cols \| rows \| none

| frame
| all \| sides \| topbot \| none

| stripes
| all \| even \| odd \| none

| width
| (0%..100%)

| format
| psv {vbar} csv {vbar} dsv
|===

색상

색상을 HEX, RGB, 또는 HSL 형식으로 작성하여 색상 표시기와 함께 렌더링하는 것이 가능합니다. 지원되는 형식 (네임드 컬러는 지원되지 않음):

  • HEX: `#RGB[A]` 또는 `#RRGGBB[AA]`
  • RGB: `RGB[A](R, G, B[, A])`
  • HSL: `HSL[A](H, S, L[, A])`

역 따옴표 안에 쓰인 색상은 색상 “칩”이 뒤따릅니다: 

- `#F00`
- `#F00A`
- `#FF0000`
- `#FF0000AA`
- `RGB(0,255,0)`
- `RGB(0%,100%,0%)`
- `RGBA(0,255,0,0.3)`
- `HSL(540,70%,50%)`
- `HSLA(540,70%,50%,0.3)`

방정식 및 수식 (STEM)

과학, 기술, 공학, 수학 (STEM) 표현을 포함해야 하는 경우, 문서의 머릿글에 있는 stem 속성을 latexmath로 설정합니다. 방정식과 수식은 KaTeX을 사용하여 렌더링됩니다: 

:stem: latexmath

latexmath:[C = \alpha + \beta Y^{\gamma} + \epsilon]

[stem]
++++
sqrt(4) = 2
++++

행렬은 stem:[[[a,b\],[c,d\]\]((n),(k))].로 쓰여질 수 있습니다.

다이어그램 및 플로차트

GitLab에서 텍스트로부터 다이어그램과 플로차트를 생성하는 것이 가능합니다. 이를 위해 Mermaid 또는 PlantUML을 사용합니다.

Mermaid

  • GitLab 13.3에서 도입. 자세한 내용은 공식 페이지를 방문하십시오. Mermaid 사용에 입문했거나 Mermaid 코드에서 문제를 식별하는 데 도움이 필요한 경우, Mermaid Live Editor는 Mermaid 다이어그램을 생성하고 문제를 해결하는 데 도움이 되는 도구입니다.

다이어그램이나 플로차트를 생성하려면 텍스트를 mermaid 블록에 입력하십시오: 

[mermaid]
----
graph LR
    A[Square Rect] -- Link text --> B((Circle))
    A --> C(Round Rect)
    B --> D{Rhombus}
    C --> D
----

Kroki

Kroki는 다수의 다이어그램 라이브러리를 지원합니다. GitLab의 Kroki를 사용하려면 관리자가 먼저 Kroki를 활성화해야 합니다. 자세한 내용은 Kroki 통합 페이지에서 확인하십시오.

Kroki가 활성화된 후 AsciiDoc 및 Markdown 문서에서 다이어그램을 생성할 수 있습니다. GraphViz 다이어그램을 사용한 예시:

AsciiDoc 

[graphviz]
....
digraph G {
  Hello->World
}
....

Markdown 

```graphviz
digraph G {
  Hello->World
}
```

PlantUML

PlantUML 통합은 GitLab.com에서 활성화되어 있습니다. 자체 설치된 GitLab에서 PlantUML을 사용할 수 있도록 하려면 관리자가 먼저 활성화해야 합니다.

PlantUML이 활성화된 후 텍스트를 plantuml 블록에 입력하십시오: 

[plantuml]
----
Bob -> Alice : hello
----

멀티미디어 

image::screenshot.png[block image,800,450]

이미지를 다시로드하려면 image:reload.svg[reload,16,opts=interactive]를 누르세요.

video::movie.mp4[width=640,start=60,end=140,options=autoplay]

GitLab은 AsciiDoc 콘텐츠에서 YouTube 및 Vimeo 비디오를 임베드하는 것을 지원하지 않습니다. 표준 AsciiDoc 링크를 사용하십시오: 

https://www.youtube.com/watch?v=BlaZ65-b7y0[비디오에 대한 링크 텍스트]

줄바꿈 

// 주제별 구분선 (수평 규칙이라고도 함)
---

// 페이지 나눔
<<<