기술 문서 작성에서 Markdown 대신 Asciidoc을 선택하는 가장 큰 이유

## 기술 문서 작성에서 Markdown 대신 **Asciidoc**을 선택하는 가장 큰 이유

Markdown이 '메모'에 최적화되어 있다면, Asciidoc은 '출판'과 '프로그래밍'의 성격을 동시에 갖고 있거든요.

핵심적인 **변수(Attributes)** 처리와 **조건부 제어(Conditional)** 기능을 정리해 드릴게요.

---

### 1. 변수 처리 (Attributes)

Asciidoc에서는 변수를 선언하고 어디서든 재사용할 수 있습니다.

### ① 변수 선언과 사용

문서 상단이나 중간에 `:변수명: 값` 형태로 선언합니다. 사용할 때는 `{변수명}`으로 호출합니다.

AsciiDoc

```java
:api-version: v1.2.3
:base-url: https://api.factory.com

== API 정보
현재 버전은 {api-version} 입니다.
모든 요청은 {base-url}/{api-version} 경로로 보내야 합니다.`
```

### ② 경로 변수화 (가장 많이 쓰는 방식)

REST Docs 작업 시 스니펫 경로를 변수로 관리하면 아주 편합니다.

AsciiDoc

```java
`:snippets: ../../../build/generated-snippets
:user-api: {snippets}/user-controller-test

include::{user-api}/http-request.adoc[]`
```

---

### 2. 조건부 제어 (Conditional Directives)

상황에 따라 특정 내용을 보여주거나 숨길 수 있습니다. (내부용/외부용 문서 분리 시 핵심 기능)

### ① `ifdef`, `ifndef` (존재 여부 체크)

특정 속성이 정의되어 있는지에 따라 텍스트를 제어합니다.

AsciiDoc

```java
`// 빌드 시 -Pinternal 옵션을 주었다고 가정
ifdef::internal[]
== [내부 전용] 관리자 가이드
관리자 전용 토큰은 DB에서 직접 조회하세요.
endif::[]

ifndef::internal[]
== 사용자 가이드
로그인 후 마이페이지에서 토큰을 확인하세요.
endif::[]`
```

### ② `ifeval` (값 비교)

변수의 값을 비교하여 제어합니다. 버전별로 다른 내용을 보여줄 때 유용합니다.

AsciiDoc\

```java
`:version: 2.0

ifeval::[{version} >= 2.0]
2.0 버전부터는 새로운 인증 방식(OAuth2)이 적용됩니다.
endif::[]`
```

---

### 3. 파일 포함 및 섹션 제어 (Include)

Markdown은 파일을 단순히 링크하지만, Asciidoc은 **파일 내용을 그대로 박아넣습니다.**

- **부분 인클루드:** 파일 전체가 아니라 특정 행(line)만 가져올 수도 있습니다.
    
    AsciiDoc
    
    ```java
    `// 5행부터 10행까지만 가져오기
    include::sample.java[lines=5..10]`
    ```
    
- **태그 인클루드:** 소스코드에 `// tag::name[]` 주석을 달아두면 해당 부분만 쏙 빼올 수 있습니다.

---

### 4. 핵심 제어문 요약표

| **구문** | **의미** | **설명** |
| --- | --- | --- |
| **`:name: value`** | 속성 정의 | 변수를 생성하고 값을 할당 |
| **`{name}`** | 속성 참조 | 정의된 변수 값을 출력 |
| **`ifdef::name[]`** | If defined | `name` 변수가 정의되어 있으면 실행 |
| **`ifndef::name[]`** | If not defined | `name` 변수가 정의되지 않았으면 실행 |
| **`ifeval::[조건]`** | If evaluate | 산술, 비교 연산 결과가 참이면 실행 |
| **`include::file[]`** | Include | 외부 파일 내용을 해당 위치에 삽입 |

---

### 💡 실전 활용 팁: 내부/외부 문서 스위칭

Gradle 빌드 시 `-PdocMode=internal` 같은 파라미터를 넘기고, `build.gradle`에서 이를 Asciidoctor 속성으로 전달하면 하나의 `.adoc` 파일로 두 버전의 HTML을 만들 수 있습니다.

**`build.gradle` 예시:**

Gradle

```java
`asciidoctor {
    attributes 'is-internal': project.hasProperty('internal')
}`
```

**`index.adoc` 예시:**

AsciiDoc

```java
`ifdef::is-internal[]
NOTE: 이 섹션은 사내망에서만 접근 가능한 API를 다룹니다.
endif::[]`
```