서식 사용법 • SNDiM

이 문서는 블로그에서 실제로 사용하는 서식만 간단히 정리합니다.

문서 기본 형식

포스트는 src/content/blog/[폴더명]/index.md 구조를 사용합니다.

permalink: 'component-guide'
title: '문서 제목'
description: '검색/공유에 노출될 설명 (50~160자)'
pubDate: 2026-04-20
heroImage: '../../../../../assets/images/draft_thumbnail.png'  # 공용 썸네일
# heroImage: './cover.png'                               # 폴더 내 이미지 사용 시
category: Guide          # Guide / Glossary / Think / News 등
tags: ['tag1', 'tag2']
draft: false             # true면 프로덕션 빌드에서 제외

heroImage: 포스트 폴더 안에 이미지를 두면 ./cover.png 형식으로 상대경로 참조 가능. 빌드 시 Astro 이미지 최적화 파이프라인 자동 적용.
category: 인덱스 페이지 slug와 연결되므로 일관되게 유지.

이미지

이미지는 문서 폴더 안에 두고 ![[파일명]] 형식으로 참조합니다. 이 형식을 사용해야 파일명에서 alt·title이 자동 설정됩니다.

![[cover-image.png]]

파일명(확장자 제외)이 그대로 alt와 title로 적용됩니다. 단락에 단독으로 있으면 <figure>로 변환되고, title이 있으면 하단에 캡션으로 표시됩니다.

인라인 이미지

텍스트 사이에 이미지를 넣으면 <img>로 렌더링되어 인라인 배치됩니다.

아이콘 ![[icon.png]] 다음 단계로 이동합니다.

단독 줄 → <figure> (블록), 텍스트와 같은 줄 → <img> (인라인).

비디오

동영상은 ![[파일명.mp4]] 문법으로 삽입합니다.

![[demo.mp4]]

mp4 지정 시 동일 경로의 webm 파일을 1순위 소스로 자동 추가합니다.

<!-- 자동 생성 결과 -->
<source src="./demo.webm" type="video/webm">
<source src="./demo.mp4" type="video/mp4">

webm, mov, ogg 등 다른 확장자는 해당 파일 단독으로 소스가 설정됩니다.

인라인 화살표

텍스트 흐름 안에서 방향 아이콘을 삽입합니다.

텍스트 토큰

공백으로 감싼 위치에서 자동 변환됩니다.

토큰	방향	결과
`:❯`	next (오른쪽)
`:>`	right
`:<`	left
`:∧`	up
`:∨`	down

설정 :❯ 계정 :❯ 보안 순서로 진행합니다.

디렉티브

명시적으로 삽입할 때는 디렉티브를 사용합니다.

::next   ::right  ::left  ::up  ::down
::n      ::r      ::l     ::u   ::d    ← 단축 별칭

여백

블록 여백 디렉티브

단락 사이 수직 간격이 필요할 때 사용합니다.

::여백        ← 기본 (0.95em)
::여백1       ← 1rem
::여백2       ← 2rem
::여백3       ← 3rem
::여백4       ← 4rem
::여백5       ← 5rem

인라인 여백

단락 내부에서 줄 간격을 넣을 때 사용합니다.

앞 문장 [여백] 뒤 문장

아코디언

:::zippy[제목]
본문 내용 (마크다운 가능)
:::

예시 아코디언

아코디언 안에서 굵게, 목록, 코드블럭 모두 사용할 수 있습니다.

여러 개 연속 작성이 가능합니다.

탭

::::tabs
:::tab[탭 이름]
내용
:::

:::tab[다음 탭]
내용
:::
::::

콜아웃

note

:::note
일반 참고 사항을 표시합니다.
:::

일반 참고 사항을 표시합니다.

caution

:::caution
주의가 필요한 내용을 표시합니다.
:::

주의가 필요한 내용을 표시합니다.

인용

:::quote[출처]
인용 내용입니다.
:::

인용 내용을 이곳에 작성합니다.

출처 이름

FAQ

::::faq
:::q[질문 내용]
답변 내용
:::

:::q[두 번째 질문]
두 번째 답변
:::
::::

FAQ는 어떻게 작성하나요?

::::faq 컨테이너 안에 :::q[질문] 아이템을 나열합니다.

코드블럭

기본

const siteName = 'SNDiM'

라인 강조

function demo() {
  return 'highlight'
}

텍스트/삽입/삭제 강조

function demo() {
  console.log('삭제')
  return true
}

파일 경로 표시

주석 첫 줄에 경로를 작성하면 파일명 탭으로 표시됩니다.

console.log('hello')

터미널 스타일

언어를 bash, sh, powershell 등으로 지정하면 터미널 프레임이 적용됩니다.

pnpm dev

키보드

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

<kbd>Ctrl</kbd> + <kbd>C</kbd> 로 복사합니다.

Ctrl + C 로 복사합니다.

다운로드 버튼

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

DOWNLOAD

내부 문서 서식 규칙

제목은 ##부터 시작 — # (h1)은 title 프론트매터가 대신함
한 섹션에는 한 주제만 작성
예시는 바로 복붙 가능한 형태로 작성
내부 링크: [문서명](/슬러그/)
이미지/파일은 문서 폴더 안에 두고 ./파일명.png 또는 ![[파일명.png]]로 참조