문서 작성 가이드

이 문서는 MDX 파일 작성 방법과 사용 가능한 컴포넌트들을 설명합니다.

기본 문법

Frontmatter

모든 MDX 파일 상단에 메타데이터를 작성합니다.

---

title: "페이지 제목"
description: "페이지 설명 (SEO용)"
keywords: ["키워드1", "키워드2"]
createdAt: "2026-01-30"
updatedAt: "2026-01-30"
---

제목 (Headings)

# h1 - 페이지 제목 (자동 숨김)
## h2 - 주요 섹션
### h3 - 하위 섹션

h1은 페이지 헤더에서 별도로 렌더링되므로 MDX 내부의 h1은 숨겨집니다.

텍스트 서식

**굵은 텍스트**
*기울임 텍스트*
`인라인 코드`
[링크 텍스트](https://example.com)

목록

- 순서 없는 목록
- 항목 2

1. 순서 있는 목록
2. 항목 2

테이블

| 헤더 1 | 헤더 2 | 헤더 3 |
|--------|--------|--------|
| 셀 1   | 셀 2   | 셀 3   |
| 셀 4   | 셀 5   | 셀 6   |

코드 블록

```json
{
  "key": "value"
}
```

지원 언어: json, javascript, typescript, python, bash, yaml, markdown

컴포넌트

Callout

정보, 경고, 팁 등을 표시하는 박스입니다.

사용법:

<Callout type="info">
정보 메시지입니다.
</Callout>

<Callout type="warning">
경고 메시지입니다.
</Callout>

<Callout type="success">
성공 메시지입니다.
</Callout>

<Callout type="error">
오류 메시지입니다.
</Callout>

<Callout type="tip" title="제목 추가 가능">
팁 메시지입니다.
</Callout>

렌더링 결과:

QuickStart

빠른 시작 안내 박스입니다.

사용법:

<QuickStart title="빠른 시작">
간단한 안내 메시지를 작성합니다.
</QuickStart>

렌더링 결과:

Steps & Step

단계별 가이드를 작성할 때 사용합니다.

사용법:

<Steps>
  <Step number={1} title="첫 번째 단계">
    첫 번째 단계의 설명입니다.
  </Step>
  <Step number={2} title="두 번째 단계">
    두 번째 단계의 설명입니다.
  </Step>
  <Step number={3} title="세 번째 단계">
    세 번째 단계의 설명입니다.
  </Step>
</Steps>

렌더링 결과:

CopyBox

복사 버튼이 있는 텍스트 박스입니다.

사용법:

<CopyBox>!추가 인사 안녕하세요!</CopyBox>

렌더링 결과:

LinkButton

외부 링크 버튼입니다.

사용법:

<LinkButton href="https://chzzk.naver.com">치지직 바로가기</LinkButton>

렌더링 결과:

HelpBox

도움말 박스입니다. 보통 페이지 하단에 사용합니다.

사용법:

<HelpBox title="문제가 있나요?">
  <a href="https://discord.gg/example">디스코드</a>에서 문의해주세요.
</HelpBox>

렌더링 결과:

CommandRef

명령어 레퍼런스 카드입니다.

사용법:

<CommandRef
  command="!업타임"
  description="현재 방송 시간을 표시합니다."
  example="!업타임"
  response="현재 방송 시간: 2시간 30분"
  cooldown="5s"
/>

렌더링 결과:

!업타임

현재 방송 시간: 2시간 30분

Props:

VariableRef

변수 레퍼런스 카드입니다.

사용법:

<VariableRef
  variable="$userName"
  description="명령어를 사용한 사용자의 닉네임"
  example="!추가 인사 안녕하세요, $userName님!"
  input="!인사"
  output="안녕하세요, 뚜또님!"
  note="익명 사용자의 경우 '익명'이 출력됩니다."
/>

렌더링 결과:

!추가 인사 안녕하세요, $userName님!

!인사

안녕하세요, 뚜또님!

Props:

API 문서 컴포넌트

API 문서 작성 시 사용하는 컴포넌트들입니다.

ApiEndpoint

API 엔드포인트 섹션을 정의합니다.

사용법:

<ApiEndpoint
  method="GET"
  path="/api/v1/example"
  description="예시 API입니다."
>
  <ApiDescription>
    {/* 왼쪽: 설명 영역 */}
  </ApiDescription>
  <ApiCodePanel>
    {/* 오른쪽: 코드 영역 */}
  </ApiCodePanel>
</ApiEndpoint>

method 옵션: GET, POST, PUT, PATCH, DELETE

ApiParams

파라미터 목록을 표시합니다.

사용법:

<ApiParams
  type="query"
  params={[
    {
      name: "page",
      type: "number",
      required: false,
      description: "페이지 번호",
      default: "1"
    },
    {
      name: "limit",
      type: "number",
      required: false,
      description: "한 페이지당 항목 수",
      default: "20"
    }
  ]}
/>

type 옵션: path, query, body, header

ApiCodeBlock

코드 블록을 표시합니다. 탭 기능을 지원합니다.

단일 코드:

<ApiCodeBlock
  title="응답"
  language="json"
  code={`{
  "success": true,
  "data": []
}`}
/>

탭 코드:

<ApiCodeBlock
  title="요청"
  tabs={[
    {
      label: "cURL",
      language: "bash",
      code: `curl -X GET "https://api.example.com/v1/data"`
    },
    {
      label: "JavaScript",
      language: "javascript",
      code: `const response = await fetch('https://api.example.com/v1/data');`
    }
  ]}
/>

ApiResponse

응답 예시를 접이식으로 표시합니다.

사용법:

<ApiResponse status={200} description="성공">
  <ApiCodeBlock
    title="응답"
    language="json"
    code={`{"success": true}`}
  />
</ApiResponse>

<ApiResponse status={400} description="잘못된 요청">
  <ApiCodeBlock
    title="응답"
    language="json"
    code={`{"success": false, "error": "오류 메시지"}`}
  />
</ApiResponse>

전체 API 문서 예시

사용법:

## 데이터 조회

<ApiEndpoint
  method="GET"
  path="/api/v1/data"
  description="데이터 목록을 조회합니다."
>
  <ApiDescription>
    <ApiParams
      type="query"
      params={[
        {
          name: "page",
          type: "number",
          required: false,
          description: "페이지 번호",
          default: "1"
        }
      ]}
    />

    ### 응답 필드

    | 필드 | 타입 | 설명 |
    |------|------|------|
    | `data` | array | 데이터 목록 |

  </ApiDescription>

  <ApiCodePanel>
    <ApiCodeBlock
      title="요청"
      language="bash"
      code={`curl -X GET "https://api.example.com/v1/data"`}
    />

    <ApiResponse status={200} description="성공">
      <ApiCodeBlock
        title="응답"
        language="json"
        code={`{"success": true, "data": []}`}
      />
    </ApiResponse>
  </ApiCodePanel>
</ApiEndpoint>

렌더링 결과:

데이터 조회

curl -X GET "https://api.example.com/v1/data?page=1&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"

{
"success": true,
"data": [
  {
    "id": 1,
    "name": "항목 1"
  },
  {
    "id": 2,
    "name": "항목 2"
  }
],
"meta": {
  "total": 100,
  "page": 1,
  "limit": 20
}
}

{
"success": false,
"error": "인증에 실패했습니다."
}

사이드바 추가

새 문서를 추가할 때 user-docs/sidebar.json을 수정합니다.

{
  "items": [
    {
      "title": "메뉴 제목",
      "href": "/docs/경로",
      "children": [
        { "title": "하위 메뉴", "href": "/docs/경로/하위" }
      ]
    }
  ],
  "slugToTitle": {
    "경로": "메뉴 제목"
  }
}