AsciiDoc : 효과적인 문서 작성을 위해 문법을 탐색하고 숙달하기

서론

대상 : 개발자, 기술 작성자, 그리고 기술 문서나 풍부한 기사 작성을 원하는 모든 사람.

AsciiDoc은 구조화된 기술 문서, 기사, 책 또는 프레젠테이션을 작성하기 위해 설계된 경량 마크업 언어입니다. 가독성, 풍부한 문법 및 HTML, PDF, DocBook 등 다양한 포맷을 생성할 수 있는 능력으로 두드러집니다. 이 글에서는 AsciiDoc의 필수 구문을 탐색하고 빠르게 시작할 수 있는 팁을 제시하겠습니다.

AsciiDoc이란 무엇인가요?

AsciiDoc는 문서 설명 언어이며, Markdown과 비슷하지만 더 강력합니다. 텍스트, 제목, 목록, 표, 코드 블록 등을 효율적으로 구조화할 수 있습니다. 그 다재다능함 덕분에 오픈 소스 프로젝트 문서화, 저서 작성, 웹 출판에 인기 있는 선택이 됩니다.

왜 AsciiDoc을 선택해야 하나요?

읽기 쉬우면서 직관적인 구문
복잡한 구조(표, 주석, 경고 등)의 네이티브 지원.
멀티 형식 생성 (HTML, PDF, ePub, DocBook…)
JBake 또는 Antora와 같은 정적 사이트 생성기와 쉽게 통합.
속성과 확장을 사용한 고급 사용자 지정.

유스케이스 다이어그램 (Use Case)

유스케이스 다이어그램은 사용자와 시스템 간의 주요 상호작용을 보여줍니다. 다음은 문서화 시스템을 위한 간단한 예시입니다:

@startuml
:Utilisateur: --> (Rédiger documentation)
:Utilisateur: --> (Générer PDF)
:Utilisateur: --> (Publier sur site web)
(Rédiger documentation) ..> (Générer PDF) : inclut
@enduml

마인드 맵 다이어그램

마인드 맵(마인드맵)은 AsciiDoc과 관련된 개념을 탐색하고 그 관계를 파악하기에 적합합니다 :

@startmindmap
* AsciiDoc
** Syntaxe
*** Titres
*** Listes
*** Blocs de code
*** Tableaux
** Extensions
*** PlantUML
*** MathJax
** Export
*** HTML
*** PDF
*** EPUB
@endmindmap

흐름도 (플럭스)

플로우 다이어그램은 AsciiDoc 문서 생성 과정을 설명할 수 있습니다 :

@startuml
start
:Écrire fichier .adoc;
:Ajouter images et diagrammes;
if (Valider la syntaxe ?) then (oui)
:Générer HTML/PDF;
:Publier ou partager;
else (non)
:Corriger erreurs;
:back to start;
endif
stop
@enduml

AsciiDoc 파일의 기본 구조

AsciiDoc 파일은 일반적으로 제목으로 시작하고, 선택적 속성이 뒤이어 오며, 그 다음 구조화된 콘텐츠가 옵니다. 다음은 최소한의 예시:

= Titre Principal
Auteur
2024-09-03
:toc:
:icons: font

Votre contenu commence ici...

기본 구문

제목과 섹션

AsciiDoc은 여러 수준의 제목을 지원합니다:

= Titre de niveau 1
== Titre de niveau 2
=== Titre de niveau 3
==== Titre de niveau 4

진하게 표시된 텍스트, 기울임 꼴, 고정폭 글꼴

*gras* _italique_ `monospace`

불릿 목록 및 번호가 매긴 목록

* Élément 1
* Élément 2

. Premier
. Deuxième
. Troisième

링크와 이미지

Lien standard : https://asciidoc.org[AsciiDoc]
Image : image::images/logo.png[AsciiDoc Logo]

코드 블록

[source,python]

def hello(): print("안녕 AsciiDoc!")

표

|===
| Colonne 1 | Colonne 2

| Valeur A
| Valeur B

| Valeur C
| Valeur D
|===

주석 및 경고

AsciiDoc은 시각 정보 블록을 제공합니다:

NOTE: Ceci est une note importante.
TIP: Conseil utile pour l’utilisateur.
WARNING: Attention à ce point.

속성 및 변수 사용

사용자 지정 속성을 사용하면 값을 재사용하거나 동작을 구성할 수 있습니다 :

:project-name: AsciiDoc Explorer

Le projet s’appelle {project-name}.

일반적인 사용 사례

오픈 소스 프로젝트 문서 (README, 기술 가이드) 도서 및 전자책 작성 - 자동 정적 웹사이트 생성 (JBake, Antora) - 기술 발표

모범 사례

일관된 제목과 자동 목차(:toc:) 를 사용하세요. - 경고를 사용하여 핵심 사항에 주의를 끌세요. - 파일을 구조화하여 유지보수를 쉽게 하세요. - 주석이 달린 코드 블록을 활용하여 예시를 보여주세요.

결론

AsciiDoc은 기술 문서나 구조화된 기사를 작성하기 위한 강력하고 접근하기 쉬운 도구입니다. 풍부한 구문과 멀티 포맷 생성이 결합되어, 까다로운 개발자와 작가에게 이상적인 도구가 됩니다. 다음 프로젝트에서 AsciiDoc을 사용해 보고 차이를 경험해 보세요!

더 나아가기

공식 문서 : https://asciidoc.org - Asciidoctor: https://asciidoctor.org - JBake와 AsciiDoc: https://jbake.org/docs/2.6.4/#asciidoc_support

경험과 팁을 댓글로 공유해 주세요!

서론