Docusaurus로 매뉴얼 만들기 #3 콘텐츠 작성 — 코드블록, Mermaid, admonition

프레임워크 Docusaurus Documentation Static Site
3 분 소요

#2에서 사이드바와 검색으로 문서의 뼈대를 잡았습니다. 이제 그 안을 채울 차례입니다. 기술 문서는 줄글만으로는 부족합니다. 명령은 코드블록으로, 흐름은 다이어그램으로, 주의할 점은 눈에 띄는 상자로 보여 줘야 독자가 빠르게 읽습니다.

이번 시리즈는 Docusaurus로 매뉴얼 만들기 6편입니다.

  • #1 설치부터 첫 문서까지
  • #2 사이드바와 검색 — 문서의 정보 구조 잡기
  • #3 콘텐츠 작성 — 코드블록, Mermaid, admonition ← 이번 글
  • #4 Cloudflare Pages로 배포하고 도메인 연결하기
  • #5 다국어와 버전 관리
  • #6 유지보수 — 검색, 접근성, 문서 문화

이번 글은 코드블록을 제대로 꾸미고, Mermaid로 다이어그램을 그리고, admonition으로 강조하는 세 가지를 다루겠습니다. Docusaurus는 이 기능 대부분을 기본으로 갖추고 있어, 켤 것이 적습니다.

코드블록 — 제목과 줄 강조 #

Docusaurus는 코드 하이라이트와 복사 버튼을 기본으로 제공합니다. 코드 펜스의 언어 뒤에 옵션을 적어 제목과 강조를 더합니다.

코드블록에 제목과 강조 
```js title="src/app.js" {2}
function add(a, b) {
  return a + b; // 이 줄이 강조됩니다
}
```

title로 파일명 띠를, {2}처럼 중괄호 안 숫자로 강조할 줄을 지정합니다. 복사 버튼은 모든 코드블록에 자동으로 붙습니다.

다이어그램 — Mermaid #

Mermaid는 별도 테마로 켭니다. 패키지를 설치한 뒤 docusaurus.config.js에서 활성화합니다.

docusaurus.config.js — Mermaid 활성화 
export default {
  markdown: { mermaid: true },
  themes: ['@docusaurus/theme-mermaid'],
};

이제 mermaid 펜스를 열면 실제 다이어그램으로 렌더됩니다.

Mermaid 흐름도 
```mermaid
flowchart LR
  A[글 작성] --> B[빌드] --> C[배포]
```

admonition — 주의와 경고 강조 #

“이건 꼭 읽어야 한다"는 내용은 줄글 사이에 묻히면 안 됩니다. Docusaurus는 admonition을 기본으로 내장합니다. 콜론 세 개로 감싸고, 뒤에 종류를 적습니다.

admonition 쓰기 
:::warning 주의
프로덕션에 적용하기 전에 반드시 백업을 먼저 하세요.
:::

종류에는 note, tip, info, warning, danger가 있고, 각각 색과 아이콘이 달라 정보, 주의, 위험을 시각적으로 구분합니다.

탭으로 나누기 #

Docusaurus의 강점은 마크다운 안에서 React 컴포넌트를 쓰는 MDX입니다. 운영체제별 명령처럼 갈래가 나뉘는 내용은 Tabs 컴포넌트로 보여 줍니다.

탭으로 나누기 
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="mac" label="macOS">brew install our-product</TabItem>
  <TabItem value="win" label="Windows">winget install our-product</TabItem>
</Tabs>

마무리 #

이번 글에서는 제목과 줄 강조가 붙는 코드블록, 코드로 관리하는 Mermaid 다이어그램, 그리고 주의, 경고를 강조하는 admonition과 탭까지 다뤘습니다. Docusaurus는 대부분의 기능이 내장되어 있어 설정이 적고, MDX 덕에 표현의 폭이 넓다는 점이 강점입니다.

다음 편에서는 이 문서를 세상에 내보냅니다. Cloudflare Pages로 배포하고 커스텀 도메인을 연결해, 누구나 주소로 접속할 수 있게 만드는 과정을 정리하겠습니다.

X