Asciidoc 기본 사용법

asciidoc에 대한 간략한 사용법을 설명합니다.

이 문서는 https://asciidoctor.org/docs/asciidoc-writers-guide/#a-new-perspective-on-tables 의 내용을 적당히 축약해서 번역한 내용입니다.

1. Asciidoctor

지금 보고 있는 문서를 포함하여 문서는 asciidoc(https://asciidoctor.org/docs/what-is-asciidoc/) 으로 작성됩니다. 기존에 문서 작성에 사용하던 docbook을 대체하는 도구이며, spring,linux 등 여러 곳에서 적용되고 있습니다.

markdown이 텍스트 기반 이메일 메시지를 작성하던 규약에서 발전 된 것이라 상대적으로 단순한 표현력만 가지고 있는것에 비해 asciidoc 는 SGML, Dockbook처럼 전문적인 문서를 작성할수 있는 매우 강력한 표현력을 제공합니다.

아스키독은 단순 텍스트 일 뿐입니다. 선호하는 텍스트 에디터로 열어서 보고 편집할수 있습니다.

2. Basic syntaxt

2.1. 문단 (Paragraphs)

문단은 빈줄로 구분됩니다. 빈줄이 없이 쓰여진 문장은 하나의 문단으로 인식 되어 이어 써집니다.

다음과 같이 작성된 문장은

소스
This journey begins one late Monday afternoon in Antwerp.
Our team desperately needs coffee, but none of us dare open the office door.

To leave means code dismemberment and certain death.

다음처럼 이어진 문장으로 만들어집니다.

출력
This journey begins one late Monday afternoon in Antwerp.Our team desperately needs coffee, but none of us dare open the office door.

To leave means code dismemberment and certain death.

2.2. 줄바꿈(line break)

문단 안에서도 줄바꿈을 쓰고 싶을때가 있습니다. 줄 끝에 +를 붙이면 줄바꿈이 됩니다.

Rubies are red, +
Topazes are blue.
출력
Rubies are red,
Topazes are blue.

또는 문단 앞에 hardbreaks 속성을 줄어도 됩니다.

소스
[%hardbreaks]
Ruby is red.
Java is black.
출력
Ruby is red.
Java is black.

문서 전체에서 소스의 줄바꿈을 출력의 줄바꿈으로 사용하고 싶다면 문서에 hardbreaks 속성을 부여하면 됩니다.

= Line Break Doc Title
:hardbreaks:

Rubies are red,
Topazes are blue.

2.3. 경고(Admonitions)

사용자의 주의를 이끌어 내기 위해 경고를 쓰고 싶을때가 있습니다. 이를 위해 다음과 같은 경고구가 준비되어 있습니다.

  • NOTE

  • TIP

  • IMPORTANT

  • CAUTION

  • WARNING

경고를 주고 싶을때 새로운 문단을 시작하고 대문자로 경고 라벨을 기술한후에 :를 붙이고 한칸 띄고 내용을 기술하면 됩니다.

소스
NOTE: 참고하고 하세요

TIP: 팁입니다

IMPORTANT: 중요합니다.

CAUTION: 주의 하세요

WARNING: 위험합니다.
출력
참고 하세요
팁입니다
중요합니다.
주의 하세요
위험합니다.

문서에 icons 속성을 설정을 이용해 아이콘을 사용할수도 있습니다.

2.4. Text formating

아스키독은 문장을 강조하기 위해 Quoted text를 사용합니다.

Quoted text는 어떤 기호로 둘러싸여서 특별한 의미를 전달하는 문장을 의미합니다.
소스
I can't believe it, we *won*!
출력

I can’t believe it, we won!

Bold, italic, and monospace formatting syntax
*bold phrase* & **char**acter**s**

_italic phrase_ & __char__acter__s__

*_bold italic phrase_* & **__char__**acter**__s__**

`monospace phrase` & ``char``acter``s``

`*monospace bold phrase*` & ``**char**``acter``**s**``

`_monospace italic phrase_` & ``__char__``acter``__s__``

`*_monospace bold italic phrase_*` &
``**__char__**``acter``**__s__**``
출력

bold phrase & characters

italic phrase & characters

bold italic phrase & characters

monospace phrase & characters

monospace bold phrase & characters

monospace italic phrase & characters

monospace bold italic phrase & characters

Quoted Text는 prefix형태로 속성을 부여할수 있습니다. 이를 통해 문서 변환 과정에서 해당 quoted text에 추가적인 스타일을 부여할수 있습니다.

예를 들어 다음과 같이 속성을 부여하면

소스
​Type the word [.userinput]#asciidoc# into the search bar.

이렇게 별도의 속성을 주면 HTML로 변환할때 해당 부분을 <span>으로 감싸고 CSS Class로 부여합니다.

HTML
<span class="userinput">asciidoc</span>

이런 방법을 이용해 자유롭게 스타일을 추가 할수 있습니다.

2.5. 치환 방지

만약 문장자체가 quoted text에서 사용하는 기호들을 사용하는 것이라면 어떻게 할까요?

이스케이프 문자로서 \ 를 해당 기호 앞에 기술해 주면 됩니다. 만약 기호가 __ 또는 **처럼 두글자로 된 기호 라면 이스케이프 문자도 두번 기술해주어야 합니다.

\*Stars* will appear as *Stars*, not as bold text.

\&sect; will appear as an entity, not the &sect; symbol.

\\__func__ will appear as __func__, not as emphasized text.

\{two-semicolons} will appear {two-semicolons}, not resolved as ;;.

2.6. 목록(List)

목록을 표시하고 싶다면 문단을 새로 시작하고 * 로 시작하는 문장을 작성하면 됩니다.

소스
* Edgar Allen Poe
* Sheri S. Tepper
* Bill Bryson
출력

  • Edgar Allen Poe

  • Sheri S. Tepper

  • Bill Bryson

목록에 제목을 기입하고 싶다면 .으로 시작하는 제목을 기입한후에 목록을 작성하면 됩니다. 이때 공백이 없어야 합니다. 있다면 추후 순서형 목록과 혼돈이 발생할수 있습니다.

소스
.Kizmet's Favorite Authors
* Edgar Allen Poe
* Sheri S. Tepper
* Bill Bryson
출력
Kizmet’s Favorite Authors

  • Edgar Allen Poe

  • Sheri S. Tepper

  • Bill Bryson

별표* 대신 -를 사용해도 됩니다.

소스
- Edgar Allen Poe
- Sheri S. Tepper
- Bill Bryson
출력

  • Edgar Allen Poe

  • Sheri S. Tepper

  • Bill Bryson

서로 다른 목록을 구분 하기 위해서는 주석을 가지는 빈 줄을 넣으면 됩니다.

소스
* Apples
* Oranges

//-

* Walnuts
* Almonds
출력

  • Apples

  • Oranges

  • Walnuts

  • Almonds

중첩된 목록을 가지고 싶다면 중첩만큼 *을 입력하면 됩니다. 최대 5단계까지 중첩 가능합니다.

소스
.Possible DefOps manual locations
* West wood maze
** Maze heart
*** Reflection pool
** Secret exit
* Untracked file in git repository
출력
Possible DefOps manual locations

  • West wood maze

    • Maze heart

      • Reflection pool

    • Secret exit

  • Untracked file in git repository

2.6.1. 순서를 가지는 목록

순서를 가지는 목록을 만들고 싶다면 숫자를 붙이면 됩니다. .소스

1. Protons
2. Electrons
3. Neutrons
출력

  1. Protons

  2. Electrons

  3. Neutrons

하지만 숫자가 아직 결정 않되었거나, 자동으로 넣고 싶다면 .으로 시작하면 됩니다.

소스
. Protons
. Electrons
. Neutrons
출력

  1. Protons

  2. Electrons

  3. Neutrons

만약 정렬된 목록을 만들기 위해 숫자를 사용하기로 하였다면, 숫자는 반드시 일련성을 가져야합니다. 또한 새로운 번호에서 시작하고 싶다면 그 숫자로 시작하면 됩니다.

소스
4. Step four
5. Step five
6. Step six
출력

  1. Step four

  2. Step five

  3. Step six

.으로 시작하는 목록에서 새로운 번호에서 시작하고 싶다면 start 속성을 주면 됩니다. .소스

[start=4]
 . Step four
 . Step five
 . Step six
출력

  1. Step four

  2. Step five

  3. Step six

역순도 가능합니다.

소스
[%reversed]
.Parts of an atom
. Protons
. Electrons
. Neutrons
출력
Parts of an atom

  1. Protons

  2. Electrons

  3. Neutrons

중첩도 가능합니다 .소스

. Step 1
. Step 2
.. Step 2a
.. Step 2b
. Step 3
출력

  1. Step 1

  2. Step 2

    1. Step 2a

    2. Step 2b

  3. Step 3

넘버링 스타일은 단계별로 다르게 적용됩니다.

Level

Numbering Scheme

Exaples

CSS Class(HTML converter)

1

Arabic

1. 2. 3.

arabic

2

Lower Alpha

a. b. c.

loweralpha

3

Lower Roman

i. ii. iii.

lowerroman

4

Upper Alpha

A. B. C.

upperalpha

5

Upper Roman

I. II. III.

upperroman

넘버링 스타일도 변경할수 있습니다.

소스
[lowerroman, start=5]
. Five
. Six
[loweralpha]
.. a
.. b
.. c
. Seven
출력

  1. Five

  2. Six

    1. a

    2. b

    3. c

  3. Seven

2.6.2. 이름 붙은 목록(Labeled list)

항목에 대한 설명을 위해서 자주 사용됩니다.

  • 구분자

  • 공백

  • 아이템

으로 구성됩니다.

소스
CPU:: The brain of the computer.
Hard drive:: Permanent storage for operating system and/or user files.
RAM:: Temporarily stores information the CPU uses during operation.
Keyboard:: Used to enter text or control items on the screen.
Mouse:: Used to point to and select items on your computer screen.
Monitor:: Displays information in visual form using text and graphics.
출력
CPU

The brain of the computer.

Hard drive

Permanent storage for operating system and/or user files.

RAM

Temporarily stores information the CPU uses during operation.

Keyboard

Used to enter text or control items on the screen.

Mouse

Used to point to and select items on your computer screen.

Monitor

Displays information in visual form using text and graphics.

설명이 아랫줄이 아니라 옆으로 나오게 할수 있습니다.

소스
[horizontal]
CPU:: The brain of the computer.
Hard drive:: Permanent storage for operating system and/or user files.
RAM:: Temporarily stores information the CPU uses during operation.
출력
[horizontal]
CPU:: The brain of the computer.
Hard drive:: Permanent storage for operating system and/or user files.
RAM:: Temporarily stores information the CPU uses during operation.

하위에 목록을 추가할수 있습니다.

소스
Dairy::
* Milk
* Eggs
Bakery::
* Bread
Produce::
* Bananas
출력
Dairy

  • Milk

  • Eggs

Bakery

  • Bread

Produce

  • Bananas

중첩도 가능하고 섞어 쓰는것도 가능합니다.

소스
Operating Systems::
  Linux:::
    . Fedora
      * Desktop
    . Ubuntu
      * Desktop
      * Server
  BSD:::
    . FreeBSD
    . NetBSD

Cloud Providers::
  PaaS:::
    . OpenShift
    . CloudBees
  IaaS:::
    . Amazon EC2
    . Rackspace
출력
Operating Systems
Linux

  1. Fedora

    • Desktop

  2. Ubuntu

    • Desktop

    • Server

BSD

  1. FreeBSD

  2. NetBSD

Cloud Providers
PaaS

  1. OpenShift

  2. CloudBees

IaaS

  1. Amazon EC2

  2. Rackspace

2.6.3. 복잡한 목록 내용

목록에 나와야 하는게 한줄짜리 문장이 전부일리가 없습니다.

기본적으로 목록은 문단 취급을 받습니다. 따라서 줄 바꿈을 해도 이어 붙습니다.

소스
* The header in AsciiDoc is optional, but if
it is used it must start with a document title.

* Optional Author and Revision information
immediately follows the header title.

* The document header must be separated from
  the remainder of the document by one or more
  blank lines and cannot contain blank lines.
출력

  • The header in AsciiDoc is optional, but if it is used it must start with a document title.

  • Optional Author and Revision information immediately follows the header title.

  • The document header must be separated from the remainder of the document by one or more blank lines and cannot contain blank lines.

목록이 하나 이상의 문단으로 구성될수도 있습니다. 그때는 다음 문단 전에 +를 넣어줍니다.

소스
* The header in AsciiDoc must start with a document title.
+
The header is optional.
출력

  • The header in AsciiDoc must start with a document title.

    The header is optional.

문단이 아닌 블럭도 추가할수 있습니다. 각 문단 또는 블럭은 + 로 계속 연결되어야 합니다.

소스
* The header in AsciiDoc must start with a document title.
+
----
= Document Title
----
+
Keep in mind that the header is optional.

* Optional Author and Revision information immediately follows the header title.
+
----
= Document Title
Doc Writer <doc.writer@asciidoc.org>
v1.0, 2013-01-01
----
출력

  • The header in AsciiDoc must start with a document title.

    = Document Title

    Keep in mind that the header is optional.

  • Optional Author and Revision information immediately follows the header title.

    = Document Title
Doc Writer <doc.writer@asciidoc.org>
v1.0, 2013-01-01

이렇게 매번 + 붙이는게 불편하다면 오픈 블럭을 사용하면됩니다.

소스
* The header in AsciiDoc must start with a document title.
+
--
Here's an example of a document title:

----
= Document Title
----

NOTE: The header is optional.
--
출력

  • The header in AsciiDoc must start with a document title.

    Here’s an example of a document title:

    = Document Title
    The header is optional.

오픈 블럭을 이용해 다른 문서를 끼워넣을수도 있습니다.

소스
* list item
+
--
include::shared-content.adoc[]
--

2.7. 링크와 이미지

URL은 자동 인식됩니다.

다음은 자동 인식되는 scheme 목록입니다.

링크는 자동으로 클릭이 걸리는데 이를 막고 싶다면 /를 앞에 붙이면 됩니다.

소스
\http://a.com

Scheme를 보이고 싶지 않다면 hide-uri-scheme 속성을 주면 됩니다.

소스
:hide-uri-scheme:
http://a.com
출력

a.com

좀더 강력한 링크를 사용하기 위해서는 link매크로를 사용합니다.

link:url[optional link text, optional target attribute, optional role attribute]
소스
search/link:https://ecosia.org[Ecosia]
출력

search/Ecosia

아스키독 문서 내부로 링크를하고 싶다면 <<id 또는 섹션 제목>> 로 할수 있습니다. .소스

The section <<images>> describes how to insert images into your document.
출력

The section [images] describes how to insert images into your document.

2.7.1. 이미지

image::를 이용해 이미지를 포함할수 있습니다.

소스
image::sunset.jpg[]

이미지 제목을 줄수 있습니다.

소스
image::sunset.jpg[Sunset]

이미지 id, 제목, 크기등에 대한 정보도 줄수 있습니다.

소스
[#img-sunset]
.A mountain sunset
[link=http://www.flickr.com/photos/javh/5448336655]
image::sunset.jpg[Sunset,300,200]

2.8. 제목 (Titles)

아스키독은 3가지 타입의 제목을 지원합니다.

  • 문서 제목

  • 섹션 제목

  • 블럭 제목

2.8.1. 문서 제목

문서 제목을 만들기 위해서는 문서의 첫 줄을 = 로 시작해야 합니다.

소스
= Lightweight Markup Languages

According to Wikipedia...

문서 제목 다음은 문서에 대한 헤더 정보를이 나올수 있습니다.

Line 1

저자이름, 이메일 주소

Line 2

리비전, 날자, 기타

소스
= Lightweight Markup Languages
Doc Writer <doc.writer@asciidoc.org>
v1.0, 2012-01-01

According to Wikipedia...

2.8.2. 문서 속성(Document attributes)

문서 헤더 다음에는 속성을 기술할수 있습니다. 속성은 :으로 둘러쌓인 이름과 값으로 구성됩니다.

소스
= User Guide
Doc Writer <doc.writer@asciidoc.org>
2012-01-01
:appversion: 1.0.0

이렇게 기술된 속성은 문서 내에서 괄호로 치환될수 있습니다. 이를 이용해 전역 변수 처럼 사용할수 있습니다.

소스
The current version of the application is {appversion}

문서 속성은 asciidoc의 기능 플래그 설정용으로도 사용됩니다. 예를 들어 목차 기능을 활성하고 싶다면 toc 속성을 주면 됩니다.

소스
:toc:

속성을 해제 하고 싶다면 !를 이름 뒤에 붙여서 표기하면 됩니다.

소스
:linkcss!:

Asciidoctor의 기본 설정값을 변경할때도 사용합니다.

소스
:imagesdir: ./images
:iconsdir: ./icons
:stylesdir: ./styles
:scriptsdir: ./js

2.8.3. 섹션 제목

섹션은 =를 이용해 표기할수 있습니다. 중첩 섹션이 될때마다 중첩 레벨이 증가합니다(0-based입니다)

소스
= Document Title (Level 0)

== Level 1 Section

=== Level 2 Section

==== Level 3 Section

===== Level 4 Section

====== Level 5 Section

== Another Level 1 Section

주요한 규칙은 다음과 같습니다.

  • 문서 타입이 book일 경우 하나의 문서에는 단 하나의 레벨 0 섹션이 있어야 합니다. (기본 문서 타입은 article입니다 )

  • 섹션 중첩 레벨을 뛰어넘기 할수 없습니다.

소스
= Document Title

= Illegal Level 0 Section (violates rule #1)

== First Section

==== Illegal Nested Section (violates rule #2)

문서 제목 이후 첫 섹션 사이의 문장은 서문에 해당합니다.

2.9. Block

다양한 기호가 의미 블럭을 구성합니다.

  • …​.: 입력한 그대로 문자열이 생성됩니다.

  • ----: Source Code 블럭

  • |===: 표(Table) 블럭

  • --: 위치에 따라 적절한 블럭으로 동작. 단 passthrough, table 제외

섹션에 번호를 붙이고 싶다면 setnums 속성을 문서에 줍니다.

소스
:setnums:

2.9.1. 블럭 제목

블럭 위에 . 으로 시작하는 제목을 줄수 있습니다. (블럭은 문단, 목록, 다른 블럭 요소가 될수 있습니다.)

소스
.TODO list
- Learn the AsciiDoc syntax
- Install AsciiDoc
- Write my document in AsciiDoc
출력
TODO list

  • Learn the AsciiDoc syntax

  • Install AsciiDoc

  • Write my document in AsciiDoc

2.10. 빌딩 블럭

2.11. 제한 블럭(Delimited block)

블럭의 범위를 지정할수 있습니다. 이미 많이 보셨죠.

소스
----
This is an example of a _listing block_.
The content inside is displayed as <pre> text.
----
출력
This is an example of a _listing block_.
The content inside is displayed as <pre> text.

이런 블럭 종류는 여러종류가 있습니다.

이름(스타일)

줄구분자

목적

치환

comment

////

출력되지 않을 설명을 기술하기 위해

none

exmple

====

예제나 경고를 표기하기 위한 블럭

normal

literal

…​.

입력하 그대로 출력하기 위한 블럭

verbatim

listing,source

----

소스코드나 키보드입력을 표현하기 위함

verbatim

open

 — 

익명 블럭. 다른 블럭 역활을 수행할수 있음.

varies

pass

raw 문자열을 처리하지 않게한다

none

quote,verse

__

인용문

normal

sidebar

****

문서 본문 옆

normal

table

|===

테이블

varies

2.12. Tables

Table delimiter로 둘러 쌓아 테이블을 표시할수 있다. 각 컬럼은 |로 분기한다. 컬럼수는 속성으로 줄수 있다.

소스
[cols=2*]
|===
|Firefox
|Web Browser

|Ruby
|Programming Language

|TorqueBox
|Application Server
|===
출력

Firefox

Web Browser

Ruby

Programming Language

TorqueBox

Application Server

헤더를 주고 싶다면 옵션을 줄수 있습니다.

소스
[cols=2*,options=header]
|===
|Name
|Group

|Firefox
|Web Browser

|Ruby
|Programming Language

|===
출력
Name Group

Firefox

Web Browser

Ruby

Programming Language

헤더는 많이 사용되기 때문에 단축 사용법을 제공합니다.

소스
[%header,cols=2*]

셀의 구분자는 | 이기 때문에 줄바꿈과 무관합니다. 줄바꿈을 통해 문단처럼 길게 이어지는 컨텐츠를 추가할수 있습니다.

소스
|===
|Name |Group |Description

|Firefox
|Web Browser
|Mozilla Firefox is an open-source web browser.
It's designed for standards compliance,
performance, portability.

|Ruby
|Programming Language
|A programmer's best friend.
|===
출력
Name Group Description

Firefox

Web Browser

Mozilla Firefox is an open-source web browser. It’s designed for standards compliance, performance, portability.

Ruby

Programming Language

A programmer’s best friend.

컬럼의 너비조절은 컬럼 cols에 줄수 있습니다

소스
[cols="2,3,5"]
|===
|Name |Group |Description

|Firefox
|Web Browser
|Mozilla Firefox is an open-source web browser.
It's designed for standards compliance,
performance and portability.

|Ruby
|Programming Language
|A programmer's best friend.

|===
출력
Name Group Description

Firefox

Web Browser

Mozilla Firefox is an open-source web browser. It’s designed for standards compliance, performance and portability.

Ruby

Programming Language

A programmer’s best friend.

컬럼안에 asciidoc 컨텐츠를 추가할수 있습니다. cols에 a 옵션을 주면 됩니다.

소스
[cols="2,3,5a"]
|===
|Name |Group |Description

|Firefox
|Web Browser
|Mozilla Firefox is an open-source web browser.
It's designed for:

* standards compliance,
* performance and
* portability.

|Ruby
|Programming Language
|A programmer's best friend.

|===
출력
Name Group Description

Firefox

Web Browser

Mozilla Firefox is an open-source web browser. It’s designed for:

  • standards compliance,

  • performance and

  • portability.

Ruby

Programming Language

A programmer’s best friend.

또는 각 셀에 직접 아스키독 지원 여부를 추가할수 있습니다.

소스
a|Mozilla Firefox is an open-source web browser.
It's designed for:

* standards compliance,
* performance and
* portability.

CSV에서 표를 만들어 낼수 있습니다.

소스
[%header,format=csv]
|===
Artist,Track,Genre
Baauer,Harlem Shake,Hip Hop
The Lumineers,Ho Hey,Folk Rock
|===
출력
Artist Track Genre

Baauer

Harlem Shake

Hip Hop

The Lumineers

Ho Hey

Folk Rock

CSV 파일을 읽어 들일수도 있습니다.

소스
[%header,format=csv]
|===
include::tracks.csv[]
|===

2.13. Source Code

  • [source] 블럭을 이용해 소스코드를 제공할수 있습니다.

  • [source,javascript] 블럭을 이용해 문법강조할 언어를 지정할수 있습니다.

  • [source,javascript,linenums] 블럭을 이용해 줄번호를 보여줄수 있습니다.

  • include 매크로를 이용해 파일을 읽어와서 소스를 첨부할수 있습니다.

    [source,ruby]
----
include::app.rb[]
----

2.14. Replacement

⇒ © 같은 기호를 표현하기 위해 => (C) 로 표기 하면 치환 됩니다. 이스케이핑을 위해 \=> 로 표기하면 변환이 되지 않습니다.

Tags: asciidoc   asciidoctor