## markdown과 차별되는 Asciidoc의 4가지 기능
Asciidoc이 "기술 문서의 끝판왕"이라 불리는 이유는 단순히 변수 때문만이 아닙니다. 마크다운으로 작업할 때 **"아, 이건 왜 안 돼?"** 싶었던 가려운 부분들을 긁어주는 강력한 기능들이 많습니다.
대표적인 차별점 4가지를 정리해 드릴게요.
---
### 1. 표준화된 경고 문구 (Admonitions)
마크다운에서는 인용구(`>`)로 대충 때우던 주의사항, 팁, 경고를 Asciidoc은 아이콘과 함께 공식적으로 지원합니다.
AsciiDoc
```java
NOTE: 참고할 만한 가벼운 내용입니다.
TIP: 이렇게 하면 더 편합니다.
IMPORTANT: 꼭 기억해야 할 핵심 내용입니다.
CAUTION: 주의가 필요한 사항입니다.
WARNING: 위험하니 절대 하지 마세요!
```
---
### 2. 강력한 테이블(Table) 제어
마크다운의 표는 조금만 복잡해져도 깨지기 일쑤지만, Asciidoc은 엑셀에 가까운 제어가 가능합니다.
- **셀 병합:** `2+` (가로 2칸 병합), `.3+` (세로 3칸 병합)
- **열 너비 비율:** `[cols="1,3,1"]` 처럼 비율을 숫자로 지정 가능
- **셀 내 서식:** 표 칸 안에 리스트를 넣거나, 소스코드를 박아넣을 수도 있습니다.
AsciiDoc
```java
[cols="1,2a"]
|===
|항목 |설명
|에러코드
|
* `E001`: 인증 실패
* `E002`: 권한 없음
|===
```
---
### 3. 소스코드 부분 가져오기 (Tag Include)
가장 강력한 기능입니다. 실제 `.java` 파일의 전체를 복사하는 게 아니라, **특정 부분만** 문서에 나타나게 할 수 있습니다. 코드가 수정되면 문서도 자동으로 바뀝니다.
- **Java 코드:**
Java
```java
// tag::important-logic[]
public void process() {
System.out.println("이 부분만 문서에 나옵니다.");
}
// end::important-logic[]
```
- **Asciidoc:**
AsciiDoc
```java
[source,java]
----
include::MyCode.java[tag=important-logic]
----
```
---
### 4. 목차(TOC)와 섹션 번호 자동화
마크다운은 목차를 만들려면 수동으로 링크를 걸거나 플러그인을 써야 하지만, Asciidoc은 선언 한 줄로 해결됩니다.
- **`:toc: left`**: 왼쪽에 고정 목차 생성
- **`:sectnums:`**: 모든 섹션에 `1.`, `1.1.`, `1.1.1.` 식의 번호를 자동 부여
- **`:sectlinks:`**: 제목을 클릭하면 해당 주소로 바로 이동하는 앵커 자동 생성
---
### 5. 한눈에 보는 비교표
| **기능** | **Markdown** | **Asciidoc** |
| --- | --- | --- |
| **태생** | 이메일/웹 게시물용 | **기술 서적/매뉴얼 출판용** |
| **변수/상수** | 지원 안 함 (수동 수정) | **속성(Attributes) 지원** |
| **파일 분할** | 링크만 가능 | **내용 통합(Include) 가능** |
| **표(Table)** | 기본 기능만 제공 | **병합, 비율 조정 등 강력함** |
| **출력 포맷** | 주로 HTML | **HTML, PDF, EPUB, DocBook 등** |
### 💡 정리하자면
마크다운이 **"가볍게 쓰는 메모장"**이라면, Asciidoc은 **"정교하게 설계된 설계도"**에 가깝습니다. 지금처럼 Spring REST Docs를 통해 API 명세서를 만드신다면, 여러 파일의 스니펫을 조립하고 버전을 관리해야 하므로 Asciidoc이 훨씬 현명한 선택입니다.
댓글
댓글 쓰기