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

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

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

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

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

이번 글은 코드블록을 제대로 꾸미고, Mermaid로 다이어그램을 그리고, asides로 강조하는 세 가지를 다루겠습니다.

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

Starlight는 Expressive Code라는 코드블록 엔진을 기본으로 갖췄습니다. 덕분에 별도 설정 없이 제목, 줄 강조, 복사 버튼이 모두 지원됩니다. 코드 펜스의 언어 뒤에 옵션을 적습니다.

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

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

다이어그램 — Mermaid #

Mermaid는 Starlight 코어에 들어 있지 않습니다. rehype-mermaid 같은 플러그인을 astro.config.mjs에 더하면, mermaid 펜스가 다이어그램으로 렌더됩니다.

astro.config.mjs — Mermaid 추가 
import rehypeMermaid from 'rehype-mermaid';

export default defineConfig({
  markdown: { rehypePlugins: [rehypeMermaid] },
  integrations: [starlight({ title: '제품 매뉴얼' })],
});

플러그인을 추가하면 다른 도구와 같은 방식으로 다이어그램을 코드로 적을 수 있습니다.

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

asides — 주의와 경고 강조 #

“이건 꼭 읽어야 한다"는 내용은 줄글 사이에 묻히면 안 됩니다. Starlight는 강조 상자를 asides라고 부르고, 기본으로 내장합니다. 콜론 세 개로 감싸고 종류를 적습니다.

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

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

탭으로 나누기 #

운영체제별 명령처럼 갈래가 나뉘는 내용은 탭으로 보여 줍니다. Starlight가 제공하는 컴포넌트를 MDX 파일에서 불러 씁니다.

탭으로 나누기 
import { Tabs, TabItem } from '@astrojs/starlight/components';

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

마무리 #

이번 글에서는 Expressive Code 코드블록, 플러그인으로 더한 Mermaid 다이어그램, 그리고 주의, 경고를 강조하는 asides와 탭까지 다뤘습니다. 코드블록과 asides가 기본으로 강력해, 설정이 적다는 점이 Starlight의 장점입니다.

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

X