이동

선택

닫기

3. EPUB 호환 AsciiDoc 표현

이 장에서는 Asciidoctor EPUB3 변환기가 가변 레이아웃 전자책으로 변환할 수 있는 의미 중심의 AsciiDoc 표현을 살펴봅니다. 2장에서 다룬 제목, 기본 문단, 기본 인라인 서식, 인용문, 순서 없는·순서 있는·작업 목록, 링크, 이미지, 기본 코드 블록, 표, 각주, 구분선은 반복하지 않습니다. 여기서는 EPUB3에서 처리할 수 있는 추가 인라인 서식, 사용자 인터페이스 매크로, 목록·블록, 문서 제어 표현, 참고 문헌을 다룹니다.

전자책은 화면 크기와 독자 설정에 따라 본문이 다시 흐르므로 고정 좌표나 특정 화면 폭에 의존하지 않는 표현을 사용하는 편이 안전합니다. 추가 처리기나 특정 EPUB 리더 기능에 의존하는 표현은 제외합니다.

EPUB 문서 속성

도서 제목 아래의 문서 속성은 EPUB 패키지의 언어, 설명, 주제, 권리 정보와 표지 등을 구성하는 데 사용됩니다. 이 속성들은 개별 챕터가 아니라 도서의 루트 문서인 book.adoc 머리말에 둡니다.

= 도서 제목
저자 이름 <author@example.com>
:doctype: book
:lang: ko
:description: 도서 내용을 설명하는 짧은 소개
:keywords: AsciiDoc, EPUB, 전자책
:copyright: Copyright (C) 2026 저자 이름
:toc:
:toclevels: 3
:front-cover-image: image:cover.png[fit=cover]

doctype`이 `book`이면 최상위 절이 EPUB 내부에서 각각의 챕터 XHTML 파일로 분할됩니다. 현재 예시 도서는 `include 지시어로 각 챕터를 루트 문서에 결합합니다.

강조 표시, 위첨자와 아래첨자

해시 기호 한 쌍은 검토하거나 주목할 내용을 강조 표시합니다. 물결표 한 쌍은 아래첨자, 캐럿 한 쌍은 위첨자를 만듭니다.

검토 대상: #이 문장#

물의 화학식: H~2~O

제곱식: x^2^ + y^2^

검토 대상: 이 문장

물의 화학식: H₂O

제곱식: x² + y²

서식 기호와 내용 사이에는 공백을 넣지 않습니다.

사용자 인터페이스 매크로

키보드 키, 버튼, 메뉴 경로는 각각 kbd, btn, menu 매크로로 표현합니다. 이 매크로를 사용하려면 문서 머리말에 experimental 속성을 설정해야 합니다. 속성 이름과 달리 사용자 인터페이스 매크로는 안정된 AsciiDoc 기능입니다.

:experimental:

새 창을 여는 단축키: kbd:[Ctrl+N]
설정을 마친 다음 btn:[저장] 버튼을 누릅니다.
내보내기 기능은 menu:파일[내보내기 > EPUB] 메뉴에서 선택할 수 있습니다.

새 창을 여는 단축키: Ctrl+N 설정을 마친 다음 저장 버튼을 누릅니다. 내보내기 기능은 파일 › 내보내기 › EPUB 메뉴에서 선택할 수 있습니다.

여러 키는 더하기 기호로 연결하고, 하위 메뉴는 대괄호 안에서 > 기호로 구분합니다.

설명 목록

설명 목록은 용어와 설명을 한 쌍으로 묶습니다. 용어 뒤에 콜론 두 개(::)를 쓰므로 일반 목록을 중첩하지 않고도 용어집이나 설정 참조를 표현할 수 있습니다.

EPUB:: 화면 크기에 맞춰 본문이 다시 흐르는 전자책 형식입니다.
XHTML:: EPUB 본문을 구성하는 문서 형식입니다.
CSS:: 전자책의 글꼴, 간격, 색상 같은 표현을 지정합니다.

EPUB: 화면 크기에 맞춰 본문이 다시 흐르는 전자책 형식입니다.
XHTML: EPUB 본문을 구성하는 문서 형식입니다.
CSS: 전자책의 글꼴, 간격, 색상 같은 표현을 지정합니다.

목록 연속과 오픈 블록

목록 항목 다음 줄에 단독 더하기 기호를 쓰면 뒤따르는 블록을 해당 항목에 연결할 수 있습니다. 하이픈 두 개로 둘러싼 오픈 블록은 여러 문단과 블록을 하나의 범용 컨테이너로 묶습니다.

. 도서 메타데이터를 확인합니다.
+
--
제목과 언어 속성이 올바른지 점검합니다.

[source,ruby]
----
puts 'metadata checked'
----
--
. 변환 결과를 확인합니다.

도서 메타데이터를 확인합니다.
제목과 언어 속성이 올바른지 점검합니다.
puts 'metadata checked'
변환 결과를 확인합니다.

단독 더하기 기호는 2장에서 설명한 줄 끝의 강제 줄바꿈 기호와 위치와 역할이 다릅니다. 오픈 블록 안에는 다른 블록을 넣을 수 있지만 오픈 블록 자체를 다시 중첩할 수는 없습니다.

경고문

짧은 경고문(admonition)은 대문자 레이블과 콜론으로 시작합니다. AsciiDoc은 NOTE, TIP, IMPORTANT, CAUTION, `WARNING`의 다섯 유형을 제공합니다.

NOTE: EPUB 리더마다 글꼴과 여백을 적용하는 방식이 다를 수 있습니다.

TIP: 여러 화면 크기와 읽기 모드에서 결과를 확인하면 문제를 일찍 찾을 수 있습니다.

CAUTION: 원본 파일을 덮어쓰기 전에 복구할 사본을 준비하십시오.

WARNING: 전자책 본문에서 고정된 페이지 번호를 참조하지 마십시오.

Note	EPUB 리더마다 글꼴과 여백을 적용하는 방식이 다를 수 있습니다.

Tip	여러 화면 크기와 읽기 모드에서 결과를 확인하면 문제를 일찍 찾을 수 있습니다.

Caution

원본 파일을 덮어쓰기 전에 복구할 사본을 준비하십시오.

Warning

전자책 본문에서 고정된 페이지 번호를 참조하지 마십시오.

여러 문단을 하나의 경고문에 넣을 때는 예제 블록 구분자인 등호 네 개를 사용합니다.

[IMPORTANT]
.배포 전 확인
====
전자책 파일을 만든 뒤 EPUB 검사 도구로 구조를 확인합니다.

한 종류의 리더에서만 확인하지 말고 화면 크기와 읽기 모드가 다른 환경에서도 검토합니다.
====

Important

배포 전 확인

전자책 파일을 만든 뒤 EPUB 검사 도구로 구조를 확인합니다.

한 종류의 리더에서만 확인하지 말고 화면 크기와 읽기 모드가 다른 환경에서도 검토합니다.

예제 블록

예제 블록은 개념의 적용 사례나 작업 결과를 본문과 구분합니다. 블록 제목은 마침표로 시작하는 줄에 작성합니다.

.파일 이름 구성 예제
====
루트 문서는 `book.adoc`으로 두고 본문 챕터는 `body` 디렉터리에 배치합니다.

파일 이름 앞에 `01`, `02`처럼 순번을 붙이면 원본에서도 읽기 순서를 쉽게 확인할 수 있습니다.
====

Example 1. 파일 이름 구성 예제

루트 문서는 book.adoc`으로 두고 본문 챕터는 `body 디렉터리에 배치합니다.

파일 이름 앞에 01, `02`처럼 순번을 붙이면 원본에서도 읽기 순서를 쉽게 확인할 수 있습니다.

사이드바

사이드바(sidebar)는 본문 흐름에서 약간 벗어나지만 관련성이 있는 배경지식이나 보충 설명을 시각적으로 분리해 제공합니다. 별표 네 개로 감싼 블록에는 여러 문단이나 다른 블록을 넣을 수 있습니다.

.가변 레이아웃
****
가변 레이아웃 EPUB에서는 독자가 글자 크기, 글꼴, 줄 간격을 바꿀 수 있습니다.

따라서 “오른쪽 상자”나 “다음 페이지”처럼 고정된 배치를 전제로 설명하지 않습니다.
****

가변 레이아웃

가변 레이아웃 EPUB에서는 독자가 글자 크기, 글꼴, 줄 간격을 바꿀 수 있습니다.

따라서 “오른쪽 상자”나 “다음 페이지”처럼 고정된 배치를 전제로 설명하지 않습니다.

리터럴 블록

리터럴 블록은 줄바꿈과 공백을 그대로 보존하지만 프로그래밍 언어나 구문 강조를 지정하지 않습니다. 명령 출력, 로그, 디렉터리 구조처럼 원문의 배열 자체가 의미를 가질 때 사용합니다.

....
asciidoc-example/
|-- book.adoc
|-- body/
|   |-- 01-chapter1.adoc
|   |-- 02-markdown-level-asciidoc.adoc
|   |-- 03-epub-compatible-asciidoc.adoc
|   |-- 04-asciidoctor-diagram.adoc
|   `-- 05-hugo-lotus-docs-compatibility.adoc
`-- media/
    `-- images/
....

asciidoc-example/
|-- book.adoc
|-- body/
|   |-- 01-chapter1.adoc
|   |-- 02-markdown-level-asciidoc.adoc
|   |-- 03-epub-compatible-asciidoc.adoc
|   |-- 04-asciidoctor-diagram.adoc
|   `-- 05-hugo-lotus-docs-compatibility.adoc
`-- media/
    `-- images/

코드 콜아웃

콜아웃(callout)은 코드의 특정 줄과 그 줄에 대한 설명을 번호로 연결합니다. 코드 블록 안의 번호와 블록 아래 설명의 번호가 서로 대응해야 합니다.

[source,ruby]
----
require 'asciidoctor'                         # <1>
Asciidoctor.convert_file 'guide.adoc'         # <2>
----
<1> `asciidoctor` 라이브러리를 불러옵니다.
<2> `guide.adoc` 파일을 HTML이나 다른 형식으로 변환합니다.

require 'asciidoctor'                         # (1)
Asciidoctor.convert_file 'guide.adoc'         # (2)

asciidoctor 라이브러리를 불러옵니다.
guide.adoc 파일을 HTML이나 다른 형식으로 변환합니다.

콜아웃은 한 코드 블록 안에서 순서대로 사용합니다. 코드가 바뀌어 설명 순서를 자주 조정한다면 숫자 대신 <.> 형식으로 자동 번호를 지정할 수도 있습니다.

운문 블록

verse 블록은 줄바꿈과 들여쓰기를 유지하면서 작성자와 출처를 함께 표시합니다. 시구, 짧은 문구, 대사처럼 행 구분이 중요한 본문에 사용할 수 있습니다.

[verse,예시 저자,전자책을 위한 문장]
____
화면은 달라져도
문장의 순서는 이어지고
독자는 자신의 크기로 읽는다.
____

화면은 달라져도
문장의 순서는 이어지고
독자는 자신의 크기로 읽는다.

— 예시 저자
전자책을 위한 문장

이산 제목

discrete 스타일을 적용한 제목은 문서의 절 구조를 새로 만들지 않는 독립 제목입니다. 목차에 추가하지 않으면서 예제 내부나 짧은 안내 영역에 제목을 붙일 때 사용합니다.

[discrete]
=== 변환 전 확인

원본 파일의 문자 인코딩과 이미지 경로를 점검합니다.

변환 전 확인

원본 파일의 문자 인코딩과 이미지 경로를 점검합니다.

이산 제목 뒤의 내용은 일반 절처럼 제목에 종속되지 않습니다. 따라서 문서 계층을 구성해야 하는 내용에는 일반 절 제목을 사용합니다.

사용자 정의 속성

사용자 정의 문서 속성은 반복되는 이름이나 버전 값을 한 곳에서 관리하는 치환 변수입니다. 속성을 선언한 뒤 중괄호로 감싼 이름을 본문에서 참조합니다.

:sample-reader: 예시 EPUB 리더
:sample-version: 3.0

이 문서는 {sample-reader}의 EPUB {sample-version} 환경을 대상으로 합니다.

이 문서는 예시 EPUB 리더의 EPUB 3.0 환경을 대상으로 합니다.

조건부 내용

조건부 지시어는 문서 속성의 존재 여부에 따라 내용을 포함하거나 제외합니다. 같은 원본에서 EPUB판과 다른 출력판의 안내 문구를 구분할 때 사용할 수 있습니다.

:ebook-edition:

ifdef::ebook-edition[]
이 문장은 전자책 판본에 포함됩니다.
endif::[]

ifndef::ebook-edition[]
이 문장은 전자책 판본에서 제외됩니다.
endif::[]

이 문장은 전자책 판본에 포함됩니다.

조건부 지시어는 문서 구조를 분석하기 전에 처리되므로 시작 지시어와 종료 지시어를 같은 블록 경계 안에 두는 것이 안전합니다.

파일 포함

긴 도서는 챕터별 파일을 include 지시어로 결합할 수 있습니다. 포함된 내용은 EPUB 변환 전에 하나의 AsciiDoc 문서로 처리됩니다.

include::body/01-chapter1.adoc[leveloffset=+1]
include::body/02-markdown-level-asciidoc.adoc[leveloffset=+1]
include::body/03-epub-compatible-asciidoc.adoc[leveloffset=+1]
include::body/04-asciidoctor-diagram.adoc[leveloffset=+1]
include::body/05-hugo-lotus-docs-compatibility.adoc[leveloffset=+1]

`leveloffset=+1`은 포함된 파일의 절 수준을 루트 문서 구조에 맞춰 한 단계 내립니다. 로컬 이미지와 포함 파일은 EPUB 변환기가 접근할 수 있도록 도서 디렉터리 안에 두어야 합니다.

주석

줄 시작의 슬래시 두 개는 한 줄 주석을 만듭니다. 슬래시 네 개로 둘러싼 주석 블록은 여러 줄의 메모나 아직 공개하지 않을 초안을 감춥니다. 주석은 변환된 문서에 포함되지 않습니다.

// 이 메모는 작성자만 확인합니다.

////
이 문단은 초안이므로 발행 결과에서 제외합니다.
여러 줄을 한 번에 감출 수 있습니다.
////

이 문장만 결과에 표시됩니다.

이 문장만 결과에 표시됩니다.

주석 구분자 안에서는 AsciiDoc 문법과 전처리 지시어도 처리되지 않습니다.

이스케이프

AsciiDoc 문법으로 해석될 수 있는 문자를 그대로 표시하려면 문자 앞에 역슬래시를 붙입니다. 역슬래시는 변환 결과에서 사라지고 뒤의 문자는 일반 텍스트로 남습니다.

다음 문자열은 굵게 표시되지 않습니다: \*별표로 감싼 문자열*

\{product-name}은 문서 속성으로 치환되지 않습니다.

다음 문자열은 굵게 표시되지 않습니다: *별표로 감싼 문자열*

{product-name}은 문서 속성으로 치환되지 않습니다.

한 문자나 하나의 문법 시작 지점만 막을 때는 역슬래시가 간결합니다. 더 넓은 범위의 치환을 제어해야 한다면 치환 단계와 블록의 용도를 함께 검토해야 합니다.

문자 치환

AsciiDoc은 입력하기 쉬운 문자 조합을 EPUB에 포함할 수 있는 유니코드 기호로 바꿉니다.

Copyright (C) 2026
AsciiDoc(TM)
등록 상표(R)
이전 <- 현재 -> 다음
원인 => 결과
계속...

AsciiDoc™

등록 상표®

이전 ← 현재 → 다음

원인 ⇒ 결과

계속…

문자 조합 전체의 치환을 막으려면 인라인 passthrough 매크로를 사용합니다. 예를 들어 `(C)`는 자동 치환되지 않고 (C)로 표시됩니다.

참고 문헌 항목과 인용

참고 문헌 항목은 대괄호 세 쌍으로 식별자를 선언합니다. 본문에서는 일반 교차 참조 문법으로 식별자를 인용하고, 목록이 속한 절에는 bibliography 스타일을 지정합니다.

자세한 문법은 <<sample-guide>>를 참고합니다.

[bibliography]
== 참고 문헌

* [[[sample-guide]]] 작성자. _AsciiDoc 안내서_. 2026.

참고 문헌 항목의 형식은 자유롭게 작성할 수 있습니다. 자동 번호 매기기나 특정 인용 양식이 필요하다면 별도의 참고 문헌 확장 기능이 필요합니다.

AsciiDoc 언어와 EPUB3 변환기의 세부 사항은 공식 문서 [ch3-language]와 [ch3-epub3]에서 확인할 수 있습니다.

EPUB 작성 시 피할 표현

절대 좌표나 고정된 화면 폭을 전제로 한 배치
EPUB 리더의 JavaScript 실행에만 의존하는 핵심 내용
특정 글꼴이 항상 사용된다고 가정한 문자 배치
HTML 통과 블록에만 의존하는 구조와 의미
“위 상자”, “오른쪽 그림”, “다음 페이지”처럼 재배치되면 의미가 달라지는 위치 참조

이러한 내용은 EPUB 문법 오류가 아니더라도 리더와 화면 크기에 따라 읽기 경험이 달라질 수 있습니다.

참고 문헌

[ch3-language] Asciidoctor Project. AsciiDoc Language Documentation.
[ch3-epub3] Asciidoctor Project. Asciidoctor EPUB3 Documentation.
[ch3-text-formatting] Asciidoctor Project. Text Formatting and Punctuation.
[ch3-description] Asciidoctor Project. Description Lists.
[ch3-admonitions] Asciidoctor Project. Admonitions.
[ch3-sidebars] Asciidoctor Project. Sidebars.
[ch3-attributes] Asciidoctor Project. Document Attributes.
[ch3-conditionals] Asciidoctor Project. Conditional Preprocessor Directives.
[ch3-ui-macros] Asciidoctor Project. UI Macros.
[ch3-callouts] Asciidoctor Project. Callouts.
[ch3-comments] Asciidoctor Project. Comments.
[ch3-prevent-substitutions] Asciidoctor Project. Escape and Prevent Substitutions.
[ch3-list-continuation] Asciidoctor Project. List Continuation.
[ch3-open-blocks] Asciidoctor Project. Open Blocks.
[ch3-discrete-headings] Asciidoctor Project. Discrete Headings.
[ch3-bibliography] Asciidoctor Project. Bibliography.

이 페이지가 도움이 되었나요?

2. Markdown 수준의 AsciiDoc 표현

4. Asciidoctor Diagram과 Mermaid