AsciiDoc

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

GitLab은 Asciidoctor gem을 사용하여 AsciiDoc 콘텐츠를 HTML5로 변환합니다. AsciiDoctor에 대한 완전한 참조는 AsciiDoctor 사용자 매뉴얼에서 찾을 수 있습니다.

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

  • 위키 페이지
  • 저장소 내부의 AsciiDoc 문서(.adoc 또는 .asciidoc)

구문

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

단락 

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

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

// 이것은 주석입니다

빈 줄은 단락을 구분합니다.

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

[%hardbreaks]
이 단락은 `hardbreaks` 옵션을 가지고 있습니다.
이제 줄 바꿈이 보존된 것을 확인하세요.

들여쓴(글꼴) 단락은 텍스트 형식을 해제하고 고정폭 글꼴로 표시되며 공백과 줄 바꿈이 보존됩니다: 

 여기에 공백 하나로 들여쓴 글락 단락입니다.
 그 결과로 *텍스트 형식*, 공백, 줄 바꿈이 보존됩니다.

상단 주의문 단락은 독자의 주의를 끕니다:

  • 주의: 이것은 간략한 참조이니 전체 문서는 https://asciidoctor.org/docs/에서 읽어보세요.
  • 팁: 목록은 들여쓸 수 있습니다. 선행하는 공백은 중요하지 않습니다.

텍스트 형식

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

*강조된 중요성* (볼드체)
_강조된 강조_ (이탤릭체)
`고정폭` (타자 글꼴)
"`더블`" 및 '`싱글`' 인쇄용 따옴표
+대체 텍스트+ (대체 비활성화)
`+글자+` (대체 비활성화가 적용된 고정폭)

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

**C** / **R** / **U** / **D**
fan__freakin__tastic
``mono``culture

대체어 

한 때 천문학자가 우주의 비밀을 발견했습니다...
(C) 1976 Arty Artisan
나는 할거야--아니, 사실은 나는 하지 않을거야.

매크로 

// 여기서 c=특수문자, q=따옴표, a=속성, r=대체어, m=매크로, p=후반 대체
유럽 아이콘:flag[role=blue]는 파란색이고 특수문자가 포함된 아이콘:circle-o[role=yellow]으로 구성되어 있습니다.
pass:c[->] 연산자는 종종 stabby 람다라고 불립니다.
AsciiDoc에서 `pass:[++]`는 우선순위가 높기 때문에 pass:c,a,r[C++ => C{pp}]로 재작성할 수 있습니다.
// 문서 헤더에 `:stem:`을 추가하여 스템 지원을 활성화하세요.
stem:[sqrt(4) = 2]

속성

사용자 정의 속성 

// 문서 헤더에 속성을 정의합니다
:이름: 값

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

당신은 Asciidoctor {asciidoctor-version}을 {url-gem}에서 다운로드하고 설치할 수 있습니다.
C{pp}는 필요하지 않고 루비만 사용하세요.
대 괄호로 감싼 단어를 출력하려면, \{이름}과 같이 선행 백슬래시를 사용하세요.

환경 속성

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

속성 설명
docname 소스 문서의 루트 이름(선행 경로나 파일 확장자 없음)
outfilesuffix 백엔드 출력에 해당하는 파일 확장자 (문서 간 상호 참조를 가능하게 하기 위해 기본값은 .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]
- Edgar Allen Poe
- Sheri S. Tepper
- Bill Bryson

정렬된 목록 

1. Step 1
2. Step 2
   1. Step 2a
   2. Step 2b
3. Step 3

로마 숫자를 기억하세요?
[upperroman]
1. is one
2. is two
3. is three

체크리스트 

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

Callout 

// 문서 머리글에 `:icons: font`를 추가하여 콜아웃 버블을 활성화합니다
[,ruby]
----
puts 'Hello, World!' # <1>
----
<1> 콘솔에 `Hello, World!`를 출력합니다.

설명 

first term:: 첫 번째 용어의 설명
second term::
두 번째 용어의 설명

문서 구조

헤더 

= 문서 제목
Author Name <author@example.org>
v1.0, 2019-01-01

섹션 

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

포함 파일

주의: AsciiDoc로 작성된 위키 페이지는 파일 확장자를 .asciidoc로 저장합니다. AsciiDoc 위키 페이지를 사용할 때는 .adoc 확장자를 .asciidoc로 변경하세요. 

include::basics.adoc[]

시스템 성능을 보장하고 악의적인 문서가 문제를 일으키지 못하도록 하기 위해 GitLab은 하나의 문서에서 처리되는 포함 지시어의 최대 제한을 적용합니다. 기본적으로 문서당 최대 32개의 포함 지시어를 가질 수 있으며, 이는 트랜시티브 종속성을 포함합니다. 처리되는 포함 지시어의 수를 사용자 정의하려면 application settings API를 사용하여 애플리케이션 설정 asciidoc_max_includes를 변경하세요.

주의: asciidoc_max_includes의 현재 최대 허용 값은 64입니다. 값이 너무 높으면 일부 상황에서 성능 문제를 유발할 수 있습니다.

별도 페이지나 외부 URL에서 포함을 사용하려면 application settings에서 allow-uri-read를 활성화하세요. 

// 어플리케이션 설정을 true로 설정하여 URI에서 내용을 읽을 수 있도록 합니다
include::https://example.org/installation.adoc[]

블록 

--
open - 일반 목적의 콘텐츠 래퍼; 목록 항목에 첨부할 유용함
--

// 주의, 중요, 노트, 꿀팁 및 경고를 포함한 인식된 유형
// 문서 머리글에 `:icons: font`를 설정하여 주의 아이콘을 활성화합니다
[NOTE]
====
주의 - 팁부터 경고까지 독자를 위한 공지
====

====
예시 - 문서화되는 개념의 데모
====

.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

자세한 내용은 공식 페이지를 방문하세요. Mermaid 사용이 처음이거나 Mermaid 코드에서 문제를 식별하는 데 도움이 필요한 경우 Mermaid 라이브 편집기가 도움이 됩니다.

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

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

Kroki

Kroki는 다섯 십 개 이상의 다이어그램 라이브러리를 지원합니다. Kroki를 GitLab에 사용하려면 GitLab 관리자가 먼저 활성화해야 합니다. 더 많은 정보는 Kroki 통합 페이지에서 확인하세요.

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

AsciiDoc 

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

Markdown 

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

PlantUML

PlantUML 통합이 GitLab.com에서 활성화되어 있습니다. Self-Managed 설치의 GitLab에서 PlantUML을 사용하려면 GitLab 관리자가 먼저 활성화해야 합니다.

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[비디오에 대한 링크 텍스트]

분할 

// 주제 분할 (수평 규칙)
---

// 페이지 분할
<<<