컨텐츠로 건너뛰기
SNDiM SNDiM SNDiM Docs

인터랙티브 컴포넌트 가이드

이 문서는 아코디언, 탭, 콜아웃, 인용, FAQ, 코드블럭, 키보드, 다운로드 버튼 등 구조와 상호작용이 있는 서식 요소를 정리한 가이드입니다. 각 항목은 작성법과 렌더링 결과를 나란히 배치해 바로 복사해서 사용할 수 있습니다. 이미지, 비디오, 색상 등 기본 서식은 기본 요소 가이드를, 순수 마크다운 문법은 마크다운 요소 가이드를 확인하세요.

아코디언

아코디언은 :::zippy[제목] 디렉티브로 생성합니다. 클릭 전까지 내용이 접혀 있어 문서 길이를 줄이면서도 정보를 유지할 수 있습니다. 자주 조회하지 않는 상세 내용, 예외 처리 절차, 보조 정보를 담기에 적합합니다.

기본

단락, 목록, 코드블럭 등 마크다운 문법을 내부에 자유롭게 사용할 수 있습니다.

작성법

:::zippy[제목]
설명 단락, 목록, 코드 등 마크다운 문법을 함께 사용할 수 있습니다.
:::

렌더링 결과

예시 아코디언

아코디언은 긴 본문을 접어 두고 필요한 시점에만 펼쳐 읽도록 설계할 때 유용합니다. 운영 문서에서는 점검 기준, 예외 처리, 승인 조건을 한 덩어리로 묶어 제공하면 문서 길이를 줄이면서도 정보 누락을 막을 수 있습니다.

  • 정책 변경 사유와 적용 일정을 함께 기록
  • 담당자와 검수 완료 시각을 같은 블록에 기록
  • 실패 시 복구 절차를 단계형으로 제공

여러 개 연속

아코디언을 연속으로 배치하면 각 항목을 독립적으로 접고 펼칠 수 있습니다. 유사한 성격의 내용을 그룹으로 구성할 때 적합합니다.

작성법

:::zippy[설치 순서]


1. 배포 대상 버전과 변경 이력 확인
2. 사전 점검 체크리스트(로그/알림/헬스체크) 실행
3. 적용 순서에 맞춰 배포 명령 실행
4. 완료 후 모니터링 지표와 기능 상태 점검


:::


:::zippy[문제 해결]


- 배포 직후 오류가 발생하면 최근 변경 범위를 우선 확인
- 롤백 기준(오류율, 응답 지연, 실패 트랜잭션)을 문서 기준과 비교
- 권한/환경 변수/외부 API 상태를 순서대로 점검


:::

렌더링 결과

설치 순서
  1. 배포 대상 버전과 변경 이력 확인
  2. 사전 점검 체크리스트(로그/알림/헬스체크) 실행
  3. 적용 순서에 맞춰 배포 명령 실행
  4. 완료 후 모니터링 지표와 기능 상태 점검
문제 해결
  • 배포 직후 오류가 발생하면 최근 변경 범위를 우선 확인
  • 롤백 기준(오류율, 응답 지연, 실패 트랜잭션)을 문서 기준과 비교
  • 권한/환경 변수/외부 API 상태를 순서대로 점검

아코디언 내부에 다른 디렉티브 같이 사용

중첩 디렉티브를 사용할 때는 바깥 컨테이너의 콜론 개수를 한 단계 더 크게 잡아야 파싱이 안정적으로 동작합니다. :::zippy 안에 :::note를 쓰려면 바깥을 ::::zippy로 올려야 합니다.

작성법

::::zippy[고급 예시]
:::note
아코디언 안에서도 콜아웃 사용 가능
:::


`코드`나 목록도 함께 작성 가능
::::

렌더링 결과

고급 예시 (중첩 동작)

아래 예시는 아코디언 내부에서 콜아웃과 코드블럭을 함께 사용하는 구조입니다. 긴 안내 문서를 작성할 때 핵심 경고와 실행 예시를 한 섹션에서 제공하면 정보 전달이 쉬워집니다.

Terminal window
pnpm build
pnpm preview
  1. 변경 요청 번호 확인
  2. 승인자 확인
  3. 배포 후 상태 공유

탭

탭은 ::::tabs + :::tab[탭명] 구조로 생성합니다. OS별 명령, 환경별 설정, 요약/상세 보기처럼 동일 주제를 여러 관점으로 나눠 제공할 때 유용합니다. 페이지 스크롤 없이 관련 정보를 한 위치에서 전환할 수 있어 문서 밀도를 높이는 데 효과적입니다.

기본 2탭

작성법

::::tabs
:::tab[요약]
이 탭은 변경 목적과 영향 범위를 먼저 전달해야 할 때 사용합니다.


- 변경 목적: 왜 이 문서를 수정했는지
- 영향 범위: 어떤 사용자/화면/기능이 달라지는지
- 확인 기준: 수정 후 무엇을 검증해야 하는지


:::


:::tab[상세]
이 탭은 실제 작업자가 그대로 따라할 수 있도록 절차 중심으로 작성합니다.


1. 사전 조건 확인
2. 실행 단계 수행
3. 결과 검증
4. 실패 시 복구 절차


:::
::::

렌더링 결과

    운영체제별 탭 (코드 포함)

    OS별로 명령이 다를 때 탭으로 분리하면 독자가 자신의 환경에 맞는 내용만 확인할 수 있습니다. 탭 안에 코드블럭을 포함할 때는 코드블럭 내부 백틱과 충돌이 없도록 쿼트 수준을 높여 작성합니다.

    작성법

    ::::tabs
    :::tab[Windows]
    

    Windows 환경에서는 설치 관리자 확인 후 실행 권한을 먼저 점검합니다.
    아래 명령은 환경 확인용 예시이며, 실제 작업 전 PATH와 버전 충돌 여부를 함께 확인하는 것이 좋습니다.
    

    ```powershell
    winget --version
    ```
    

    - 설치 경로 확인
    - 관리자 권한 필요 여부 확인
    - 실행 로그 저장 위치 확인
    

    :::
    

    :::tab[macOS]
    

    macOS 환경에서는 쉘 설정 파일(`.zshrc`, `.zprofile`) 반영 여부를 먼저 확인합니다.
    동일 명령이어도 사용자 셸 설정에 따라 결과가 달라질 수 있으므로 버전 정보와 경로 정보를 함께 기록합니다.
    

    ```bash
    sw_vers
    ```
    

    - OS 버전 기록
    - 셸 환경 변수 확인
    - 도구 경로 충돌 확인
    

    :::
    ::::

    렌더링 결과

      콜아웃

      콜아웃은 본문 흐름 중에 독자의 시선을 끌어야 하는 정보를 강조 블록으로 표시합니다. :::note는 참고/안내용, :::caution은 주의가 필요한 경고/위험 내용에 사용합니다.

      note

      작성법

      :::note
      이 설정은 선택 항목이며 기본값으로도 기능 사용이 가능합니다.
      :::

      렌더링 결과

      caution

      작성법

      :::caution
      운영 값 변경은 승인 절차를 거친 뒤에만 진행합니다.
      :::

      렌더링 결과

      update

      페이지가 비정기적으로 업데이트됨을 안내하는 고정 텍스트 콜아웃입니다. site.config.ts의 updateNotice 항목에서 텍스트를 수정할 수 있습니다.

      작성법

      ::update

      렌더링 결과

      ::update

      noti

      튜토리얼 환경 작성 안내 콜아웃입니다. site.config.ts의 notiText 항목에서 텍스트를 수정할 수 있으며, {{siteUrl}}은 설정된 사이트 URL로 자동 치환됩니다.

      작성법

      ::noti

      렌더링 결과

      ::noti

      env

      튜토리얼 환경 정보를 모노스페이스 스타일로 표시합니다. ::noti 뒤에 ---와 함께 사용합니다.

      작성법

      :::env
      윈도우 11 Pro (빌드: 22631.3296)
      :::

      렌더링 결과

      윈도우 11 Pro (빌드: 22631.3296)

      url

      URL을 클릭 가능한 바로가기 카드로 표시합니다. 위아래 보더 라인, 호버 배경 전환, 블록 전체 클릭 시 외부 링크로 이동합니다.

      작성법

      :::url
      https://snd.im/
      :::

      렌더링 결과

      point

      SEO 3줄 요약 등 핵심 내용을 강조할 때 사용하는 황색 별 아이콘 콜아웃입니다.

      작성법

      :::point
      이 글의 핵심 내용을 3줄로 요약합니다.
      환경 설정 없이 바로 사용할 수 있으며, 멀티라인도 동일하게 동작합니다.
      SEO 최적화를 위해 포스트 상단에 배치하면 효과적입니다.
      :::

      렌더링 결과

      이 글의 핵심 내용을 3줄로 요약합니다. 환경 설정 없이 바로 사용할 수 있으며, 멀티라인도 동일하게 동작합니다. SEO 최적화를 위해 포스트 상단에 배치하면 효과적입니다.

      인용

      :::quote[출처] 디렉티브는 외부 문구나 내부 정책 원칙을 강조해서 인용할 때 사용합니다. 일반 마크다운 > 인용문보다 시각적으로 더 부각됩니다. 대괄호 안에 출처나 제목을 적으면 하단에 표시됩니다.

      작성법

      :::quote[문서 작성 원칙]
      문서의 목적은 정보를 많이 담는 것이 아니라, 필요한 정보를 빠르게 찾고 같은 방식으로 재현할 수 있게 만드는 것입니다.
      :::

      렌더링 결과

      문서의 목적은 정보를 많이 담는 것이 아니라, 필요한 정보를 빠르게 찾고 같은 방식으로 재현할 수 있게 만드는 것입니다.

      문서 작성 원칙

      FAQ

      FAQ는 ::::faq + :::q[질문] 구조로 작성합니다. 동일한 질문이 반복되는 문서에서 응답 품질을 균일하게 유지할 때 효과적입니다. 질문 클릭 시 답변이 펼쳐지는 아코디언 방식으로 렌더링됩니다.

      작성법

      ::::faq
      :::q[FAQ 섹션은 어떤 상황에서 사용하는 것이 적절한가요?]
      FAQ는 동일한 질문이 반복되는 문서에서 응답 품질을 균일하게 유지할 때 효과적입니다.
      :::
      ::::

      렌더링 결과

      FAQ 섹션은 어떤 상황에서 사용하는 것이 적절한가요?

      FAQ는 동일한 질문이 반복되는 문서에서 응답 품질을 균일하게 유지할 때 효과적입니다.

      코드블럭

      코드블럭은 astro-expressive-code 기반으로 렌더링됩니다. 언어 지정, 줄 강조, 텍스트 마킹, 파일명 표시, 터미널 스타일 등 다양한 옵션을 백틱 세 개 뒤에 붙여 사용합니다.

      기본

      const documentTitle = 'Sample Documentation'

      라인 강조

      function demo() {
        return 'highlight'
      }

      터미널 스타일

      Terminal window
      pnpm dev

      키보드

      HTML <kbd> 태그로 키보드 단축키를 표시합니다.

      Ctrl + C 로 복사합니다.

      다운로드 버튼

      .center-button + .button CSS 클래스를 사용해 중앙 정렬된 다운로드 버튼을 만듭니다.

      <div class="center-button">
        <a href="https://example.com/file.zip" class="button">DOWNLOAD</a>
      </div>
      DOWNLOAD

      분리선

      위 단락 내용

      아래 단락 내용