058 | Asciidocs, Asciidoctor

🎈 Asciidoc

Asciidoc은 Spring Rest Docs를 통해 생성되는 텍스트 기반 문서로, 기술 문서 작성을 위해 설계된 마크다운 언어이다. 

 

🧩 목차

= 문서 제목
:sectnum:
:toc: left
:toclevels: 1~6
:toc-title: 타이틀
:source-highlighter: prettify

• = 문서 제목: Ascii 문법으로 목차를 구성한다.
• :sectnum:: 각 섹션에 넘버링을 한다.
• :toc: left: 문서의 목차를 어디에 구성할 것인지 정한다. left는 목차를 왼쪽으로 한다.
• :toclevels: 3: 목차에 표시할 각 섹션의 제목의 level(HTML기준 h1~h6)을 정한다. 3으로 지정할시 === 까지의 제목을 목차에 포함시킨다.
• :toc-title: 타이틀: 목차의 제목을 지정할 수 있다.
• source-highlighter: prettify: 소스코드 하이라이트를 지정한다.

🧩 박스 문단

***
문단 제목

  문단의 내용이다. Spring MVC 기반의 REST API 기반 애플리케이션을 공부하고 있다.
CAUTION: 경고문구 기재

***

• ***: 단락을 구분짓는 수평선을 추가해준다.
• : 문단 제목 다음 한 줄 띄우고 한 칸 들여쓰기를 하면 박스 문단을 사용할 수 있다.
• CAUTION: 경고문구를 추가할 수 있다. NOTE:, TIP:, IMPORTANT:, WARNING: 등을 사용할 수 있다.

🎈 Asciidoctor

Spring Rest Docs에서 Asciidoc 포맷의 문서를 파싱해서 HTML 5, 매뉴얼 페이지, PDF 및 EPUB 3 등의 파일로 변환한 문서를 생성하는 툴이다.

 

🧩 문서 스니핏

Spring Rest Docs 테스트케이스를 전부 통과하면 build/generated-snippets/idenntifier 디렉토리에 .adoc 스니핏 문서가 생성된다.

Gradle에서 task > build를 실행하면 Asciidoctor가 각각의 스피닛 문서들을 모아 index.adoc → index.html, 하나의 html 파일로 변환 후 특정 디렉토리(src/main/resources/static/docs)에 저장해준다.

• index.adoc에 스피닛 포함하기

.snippet1
include::{snippets}/identifier/snippet1.adoc[]

.snippet2
include::{snippets}/identifier/snippet2.adoc[]

• .snippet: 스니핏 제목 표현
• include::{snippets}/identifier/snippet.adoc[]
  • include: Asciidoctor에서 사용하는 매크로로, 스니핏을 문서에 포함할 때 사용한다.
  • ::: 매크로를 사용한다.
  • {snippets}: 해당 스니핏이 생성되는 디폴트 경로이며 build.gradle에 설정한 snippersDir 변수를 참조하는데 사용할 수 있다.

✅ Ref.

https://docs.spring.io/spring-restdocs/docs/current/reference/html5/#working-with-asciidoctor

Spring REST Docs

https://docs.asciidoctor.org/asciidoc/latest/toc/

AsciiDoc - Automatic Table of Contents