AsciiDoc

Tier: Free, Premium, Ultimate

Offering: GitLab.com, Self-managed, GitLab Dedicated

GitLab은 Asciidoctor 젬을 사용하여 AsciiDoc 콘텐츠를 HTML5로 변환합니다.

자세한 Asciidoctor 참조는 Asciidoctor 사용자 설명서를 참조하세요.

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

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

Syntax

가장 일반적으로 사용되는 AsciiDoc 문법에 대한 간략한 참조입니다.

AsciiDoc 문법에 대한 전체 문서는 https://asciidoctor.org/docs/에서 확인할 수 있습니다.

Paragraphs 

A normal paragraph.
Line breaks are not preserved.

라인 코멘트는 //로 시작하는 줄로 건너뛰어집니다:

// this is a comment

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

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

[%hardbreaks]
This paragraph carries the `hardbreaks` option.
Notice how line breaks are now preserved.

들여쓰기된 (리터럴) 단락은 텍스트 서식을 비활성화하고,

공백과 줄 바꿈을 보존하며, 고정폭 글꼴로 표시됩니다:

 This literal paragraph is indented with one space.
 As a consequence, *text formatting*, spaces,
 and lines breaks will be preserved.

Admonition 단락은 독자의 주의를 끌도록 설계되었습니다:

  • NOTE: This is a brief reference, please read the full documentation at https://asciidoctor.org/docs/.
  • TIP: Lists can be indented. Leading whitespace is not significant.

Text Formatting

Constrained (applied at word boundaries)

*strong importance* (aka bold)
_stress emphasis_ (aka italic)
`monospaced` (aka typewriter text)
"`double`" and '`single`' typographic quotes
+passthrough text+ (substitutions disabled)
`+literal text+` (monospaced with substitutions disabled)

Unconstrained (applied anywhere)

**C**reate+**R**ead+**U**pdate+**D**elete
fan__freakin__tastic

monoculture ```

Replacements

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

Macros

// where c=specialchars, q=quotes, a=attributes, r=replacements, m=macros, p=post_replacements
The European icon:flag[role=blue] is blue & contains pass:[************] arranged in a icon:circle-o[role=yellow].
The pass:c[->] operator is often referred to as the stabby lambda.
Since `pass:[++]` has strong priority in AsciiDoc, you can rewrite pass:c,a,r[C++ => C{pp}].
// activate stem support by adding `:stem:` to the document header
stem:[sqrt(4) = 2]

Attributes

User-defined attributes

// define attributes in the document header
:name: value

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

You can download and install Asciidoctor {asciidoctor-version} from {url-gem}.
C{pp} is not required, only Ruby.
Use a leading backslash to output a word enclosed in curly braces, like \{name}.

Environment attributes

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

Attribute Description
docname Root name of the source document (no leading path or file extension).
outfilesuffix File extension corresponding to the backend output (defaults to .adoc to make inter-document cross references work).

링크 

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`를 추가하여 호출 버블을 활성화합니다
[,ruby]
----
puts 'Hello, World!' # <1>
----
<1> 콘솔에 `Hello, World!`를 출력합니다.

설명 

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

문서 구조

헤더 

= 문서 제목
저자 이름 <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개의 포함 지시문을 가질 수 있습니다. 처리된 포함 지시문의 수를 사용자 정의하려면 asciidoc_max_includes 애플리케이션 설정을 변경하세요. 애플리케이션 설정 API를 사용해 주세요.

참고: 현재 허용된 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 - 독자를 위한 주의사항, tip에서 alert까지의 심각도로 범위가 다양함
====

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

.Toggle Me
[%collapsible]
====
collapsible - 이러한 세부정보는 제목을 클릭하여 표시됩니다
====

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

....
literal - 프로그램 출력을 포함하는 전시
....

----
listing - 프로그램 입력, 소스 코드 또는 파일의 내용을 포함하는 전시
----

[,language]
----
source - (색상 강조) 구문 강조가 추가된 목록
----

\```language
fenced code - 소스 블록을 위한 shorthand 구문
\```

[,attribution,citetitle]
____
quote - 인용 또는 발췌; 출처 제목이 있는 귀속은 선택 사항입니다
____

[verse,attribution,citetitle]
____
verse - 문학적 발췌, 종종 시; 출처 제목이 있는 귀속은 선택 사항입니다
____

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

// 문서 헤더에 `:stem:`을 추가하여 스템 지원을 활성화하세요.
[stem]
++++
x = y^2
++++

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

테이블 

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

| 옵션
| 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)

과학(Science), 기술(Technology), 공학(Engineering) 및 수학(Math) (STEM) 표현을 포함해야 하는 경우, 문서 헤더에 stem 속성을 latexmath로 설정하세요.

방정식 및 수식은 KaTeX를 사용하여 렌더링됩니다:

:stem: latexmath

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

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

A 행렬은 stem:[[[a,b\],[c,d\]\]((n),(k))]로 작성할 수 있습니다.

다이어그램 및 플로우차트

GitLab에서 Mermaid 또는 PlantUML을 사용하여 텍스트에서 다이어그램과 플로우차트를 생성할 수 있습니다.

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는 12개 이상의 다이어그램 라이브러리를 지원합니다.

GitLab에서 Kroki를 사용 가능하게 하려면, GitLab 관리자가 먼저 이를 활성화해야 합니다.

더 알아보기 페이지에서 확인하세요.

Kroki가 활성화된 후에는 AsciiDoc 및 Markdown 문서에서 다이어그램을 생성할 수 있습니다.

다음은 GraphViz 다이어그램을 사용하는 예입니다:

AsciiDoc

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

Markdown

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

PlantUML

PlantUML 통합은 GitLab.com에서 활성화되어 있습니다. GitLab의 자가 관리 설치에서 PlantUML을 사용 가능하게 하려면, GitLab 관리자가 이를 활성화해야 합니다.

PlantUML이 활성화된 후에는 plantuml 블록에 텍스트를 입력합니다:

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

멀티미디어 

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

Press image:reload.svg[reload,16,opts=interactive] to reload the page.

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

GitLab은 AsciiDoc 콘텐츠에 YouTube 및 Vimeo 비디오를 삽입하는 것을 지원하지 않습니다.

표준 AsciiDoc 링크를 사용하세요:

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

구분선 

// 주제 구분선 (aka 수평 구분선)
---

// 페이지 구분
<<<