AsciiDoc에서 색이 있는 사각형 표시하기: 실용 가이드

게시: 01 November 2025

소개

기술 문서를 작성할 때, 특히 스타일 가이드나 사용자 인터페이스 사양을 작성할 때는 색상 팔레트를 표시해야 하는 경우가 자주 발생합니다. AsciiDoc은 문서 작성에 매우 강력하지만, 색상 샘플을 표시하기 위한 네이티브 구문을 제공하지 않습니다. 이 글에서는 이 문제를 살펴보고 HTML 삽입을 기반으로 한 우아한 솔루션을 제시합니다.

문제

사용 컨텍스트

상상해 보세요. 웹 애플리케이션 테마의 CSS 변수를 문서화하고 있습니다. 다음이 필요합니다:

  1. 16진수 색상 코드 나열

  2. 각 색상의 시각적 미리보기 표시

  3. 소스 문서의 가독성 유지

  4. JBake와 같은 정적 사이트 생성기와 호환성을 보장해야 합니다.

@startuml
left to right direction
skinparam packageStyle rectangle

actor "기술 작가" as writer
actor "독자" as reader

rectangle "문서 AsciiDoc" {
  usecase "색상 팔레트 문서화" as UC1
  usecase "16진수 코드 표시" as UC2
  usecase "색상 시각화" as UC3
  usecase "정적 사이트 생성" as UC4
  usecase "문서 참조" as UC5
}

writer --> UC1
UC1 ..> UC2 : include
UC1 ..> UC3 : include
UC1 --> UC4
UC4 --> UC5
UC5 <-- reader
@enduml

가능한 접근 방법

여러 가지 해결책을 고려하여 AsciiDoc 문서에서 색상을 표시할 수 있습니다.

@startuml
skinparam componentStyle rectangle

package "가능한 해결책" {
  component "유니코드 문자" as unicode
  component "외부 이미지" as images
  component "사용자 정의 CSS 역할" as css
  component "HTML 삽입" as html
}

package "평가 기준" {
  component "간결함" as simple
  component "휴대성" as portable
  component "맞춤 설정" as custom
  component "유지 보수" as maintain
}

unicode -down-> simple : ✓
unicode -down-> portable : ✓
unicode -down-> custom : ✗

images -down-> simple : ✗
images -down-> portable : ✗
images -down-> custom : ✓

css -down-> simple : ~
css -down-> portable : ✗
css -down-> custom : ✓

html -down-> simple : ✓
html -down-> portable : ✓
html -down-> custom : ✓✓
html -down-> maintain : ✓

note right of html
  Solution recommandée
end note
@enduml

옵션 1: 유니코드 문자

유니코드 문자를 사용하는`■`(■)은 간단하지만 제한적입니다:

* ■ --accent-color: #7952b3 (violet Bootstrap)

제한 사항 : 색상을 제어할 수 없으며, 시스템 글꼴에 따라 달라집니다.

옵션 2 : 외부 이미지

각 색상에 대해 PNG 또는 SVG 이미지를 생성합니다 :

* image:colors/violet.svg[width=16] --accent-color: #7952b3

제한점 : 무거운 유지보수, 파일 증가, 자동 동기화 없음.

옵션 3: 사용자 정의 CSS 역할

CSS 클래스를 정의하고 AsciiDoc 역할을 통해 적용하기 :

* [.color-violet]##■## --accent-color: #7952b3

제한 사항 : 외부 스타일 시트가 필요합니다, 모든 가능한 색상에 대한 사전 정의.

옵션 4 : HTML 주입 (선택된 솔루션)

매크로 사용``HTML을 인라인 스타일과 함께 삽입하기 위해 :

* pass:[<span style="display:inline-block;width:1em;height:1em;
background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>]
--accent-color: #7952b3 (violet Bootstrap)

해결책: 를 사용한 HTML 인젝션

작동 원리

매크로``AsciiDoc는 해석되지 않은 원시 콘텐츠를 삽입할 수 있게 해줍니다. 이를 통해 인라인 CSS 스타일이 적용된 HTML을 직접 삽입할 수 있습니다.

@startuml
participant "문서
아스키독" as doc
participant "프로세서\nAsciiDoc" as processor
participant "pass:[] 매크로" as pass
participant "HTML
최종" as html

doc -> processor : Analyse document
processor -> pass : Détecte pass:[]
pass -> processor : Retourne HTML brut
processor -> html : Insère sans transformation
html -> html : Navigateur applique styles
@enduml

구현

다음은 주입할 HTML 구조입니다 :

<span style="display:inline-block;
             width:1em;
             height:1em;
             background:#7952b3;
             vertical-align:middle;
             margin-right:0.5em">
</span>

CSS 속성 설명

속성 기능

display:inline-block

width/height를 설정할 수 있으며 인라인 흐름을 유지합니다

width:1em; height:1em

글꼴 크기 대비 정사각형 크기 (반응형)

background:#7952b3

표시할 색상 (필요에 따라 변수)

vertical-align:middle

인접한 텍스트와 사각형을 정렬하세요

margin-right:0.5em

정사각형과 텍스트 사이의 간격

완전한 예시

다음은 테마 팔레트를 문서화하는 예시입니다:

== Thème Clair

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#f8f9fa` (blanc cassé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#212529` (noir très foncé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#7952b3` (violet Bootstrap)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#61428f;vertical-align:middle;margin-right:0.5em"></span>] --accent-hover: `#61428f` (violet plus foncé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --card-bg: `#ffffff` (blanc)

다음 렌더링을 생성하는 :

라이트 테마

  • 통과:[<span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary:`#f8f9fa`(아이보리)

  • --text-primary:`#212529`(매우 진한 검정)

  • --accent-color:`#7952b3`(보라색 Bootstrap)

  • --accent-hover:`#61428f`(더 어두운 보라색)

  • --card-bg:`#ffffff`(흰)

최적화 및 모범 사례

밝은 색 관리

매우 밝은 색 (흰색, 매우 밝은 회색)의 경우 흰색 배경에서 보이도록 테두리를 추가하세요:

<span style="display:inline-block;width:1em;height:1em;
background:#ffffff;border:1px solid #ccc;
vertical-align:middle;margin-right:0.5em"></span>

회색 테두리 (border:1px solid #ccc) 흰색 배경 위의 흰색 사각형의 경계를 지정할 수 있다.

정사각형 크기 조정

필요에 따라 사각형의 크기를 조정할 수 있습니다 :

* pass:[<span style="display:inline-block;width:1.5em;height:1.5em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] Grand carré
* pass:[<span style="display:inline-block;width:0.8em;height:0.8em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] Petit carré

단위 사용`em`사각형이 글꼴 크기에 맞게 조정됨을 보장합니다.

변형 만들기

특정 요구 사항을 위해 다양한 형태를 만들 수 있습니다:

색 원

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;border-radius:50%;vertical-align:middle;margin-right:0.5em"></span>] Cercle violet

색 테두리가 있는 정사각형

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:3px solid #7952b3;vertical-align:middle;margin-right:0.5em"></span>] Bordure violette

솔루션 아키텍처

@startuml
package "문서 워크플로우" {
  [Document AsciiDoc\navec pass macro] as asciidoc
  [Processeur JBake] as jbake
  [Site HTML statique] as html
  [Navigateur Web] as browser
}

asciidoc --> jbake : 1. Compilation
jbake --> html : 2. Génération
html --> browser : 3. Affichage
browser --> browser : 4. Rendu CSS

note right of asciidoc
  Contient les balises
  pass:[] avec HTML inline
end note

note right of jbake
  Préserve le HTML
  dans pass:[]
end note

note right of browser
  Applique les styles
  inline CSS
end note
@enduml

장점과 한계

장점

  • ✓ 자율성 : 외부 파일에 대한 의존 없음

  • ✓ 이식성 : 모든 AsciiDoc 프로세서와 작동합니다

  • ✓ 동기화 : 색상 코드는 HTML에 직접 있습니다.

  • ✓ 유연성 : 스타일의 완전한 커스터마이징

  • ✓ Maintenance : 간단한 16진수 코드 수정

  • ✓ 호환성 JBake : 정적 사이트 생성기와 완벽하게 호환됩니다

제한

  • ✗ 장황함 : 반복적인 HTML 코드가 AsciiDoc 소스에 있습니다.

  • ✗ 소스 가독성 : 소스 문서가 덜 깔끔합니다.

  • ✗ 접근성 : 네이티브 대체 텍스트가 없습니다(수동으로 추가해야 함)

접근성 개선

스크린 리더가 사각형에 접근할 수 있게 만들려면 :

* pass:[<span role="img" aria-label="Couleur violet Bootstrap"
style="display:inline-block;width:1em;height:1em;background:#7952b3;
vertical-align:middle;margin-right:0.5em"></span>]
--accent-color: `#7952b3` (violet Bootstrap)

속성들`role="img"` et `aria-label`이들은 보조 기술이 시각적 콘텐츠를 이해하고 설명하도록 허용한다.

구체적인 예시: 주제 문서

다음은 여러 주제를 문서화한 완전한 예시입니다:

= Guide des couleurs de l'application

== Thème Clair (`:root`)

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#f8f9fa` (blanc cassé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#212529` (noir très foncé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#7952b3` (violet Bootstrap)

== Thème Sombre (`[data-bs-theme="dark"]`)

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#212529` (noir très foncé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #999;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#ffffff` (blanc)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#0d6efd;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#0d6efd` (bleu Bootstrap)

== Thème Contraste Élevé (`[data-bs-theme="high-contrast"]`)

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#000000;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#000000` (noir)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #000;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#ffffff` (blanc)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#00ff00;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#00ff00` (vert vif)

결론

매크로를 통한 HTML 삽입``AsciiDoc은 기술 문서에 색상 샘플을 표시하는 우아하고 실용적인 솔루션을 제공합니다. 약간 장황할 수 있지만, 이 접근 방식은 최대 이식성을 보장하고 유지 관리를 간소화합니다.

이 기술은 외부 구성이 필요 없으며, 추가 스타일시트도 필요하지 않으며, JBake 및 모든 표준 AsciiDoc 프로세서와 즉시 작동합니다.

첫 번째 색이 있는 사각형을 만든 뒤에는, HTML 코드를 복사해서 붙여넣고 16진수 코드를 변경하면 빠르게 전체 팔레트를 만들 수 있습니다.

이 기술은 맞춤형 시각적 렌더링이 필요한 다른 사용 사례로 확장될 수 있습니다: 아이콘, 배지, 간단한 그래프, 또는 스타일을 정확히 제어해야 하는 모든 시각적 요소.

자원

2025-11-01에 게시된 기사

관련 기사

HyperFrames-Gradle : AsciiDoc을 MP4 비디오로 변환
31 May 2026
나의 LLM 소비 감사 : SQLite, OpenCode, Ollama Cloud, 그리고 왜 나의 프로 구독이 세계 시장을 폭발시키는가?
18 May 2026
아키텍처 « 독립 플러그인 + 소비자 루트 » : 왜 내 Gradle 빌드가 중복되는가
14 May 2026
추천 엔진으로서의 Knowledge Graph: 시간 순서의 « 관련 기사 »를 죽인 방법
12 May 2026