마크다운 요소 가이드

이 문서는 순수 마크다운 문법만 모아서 확인할 수 있는 기본 가이드입니다. 운영 문서, 릴리스 노트, 기술 설명서를 작성할 때 가장 먼저 참고하는 기준 페이지로 사용할 수 있습니다. 확장 서식이 필요하면 기본 요소 가이드를, 아코디언, 탭, 콜아웃 등 인터랙티브 컴포넌트는 인터랙티브 컴포넌트 가이드를 확인하세요.

순수 마크다운은 작성 도구가 달라도 호환성이 높고, 변경 이력 비교가 쉬워 협업에 유리합니다. 특히 리뷰 주기가 짧은 팀에서는 단순한 문법만으로도 충분히 명확한 문서를 만들 수 있습니다.

문서 기본 구조

모든 문서는 --- 사이에 YAML 프론트매터를 작성하는 것으로 시작합니다. 이 메타데이터가 URL, 제목, 카테고리, 검색 노출 등 문서 전반을 제어합니다.

permalink: '문서-슬러그'
title: '문서 제목'
description: '검색/공유용 설명'
pubDate: 2026-04-23
category: Guide
tags: ['guide', 'markdown']
draft: false

• permalink - URL slug를 파일 경로와 무관하게 직접 지정합니다. 짧고 명확하게 작성하세요.
• title - 페이지 <h1> 역할을 합니다. 본문에서는 ##(h2)부터 시작해야 합니다.
• description - SEO 메타 설명과 공유 카드에 사용됩니다. 50~160자를 권장합니다.
• draft: true - 프로덕션 빌드에서 제외됩니다. 개발 서버에서는 정상 노출됩니다.

제목(Heading)

제목은 문서 계층을 나누는 가장 기본 요소입니다. title 프론트매터가 h1을 담당하므로 본문에서는 ##(h2)부터 시작합니다. 제목만 읽어도 문서 전체 구조를 파악할 수 있어야 합니다.

H2 제목 예시

H2는 문서의 큰 단위를 구분할 때 사용합니다. 섹션 이름은 기능 또는 작업 목적이 드러나게 작성하는 것이 좋습니다. 목차(TOC)에 자동으로 등록되므로 독자가 원하는 섹션으로 바로 이동할 수 있습니다.

H3 제목 예시

H3는 H2 하위 항목을 세부화할 때 사용합니다. 동일한 깊이의 제목은 표현 형식을 맞추면 읽기 흐름이 안정됩니다. 단계형 문서에서는 입력, 처리, 검증 순서로 정렬하면 효과적입니다.

H4 제목 예시

H4는 꼭 필요한 경우에만 사용하는 것을 권장합니다. 제목 계층이 과도하게 깊어지면 탐색 속도가 느려집니다. 일반적으로 H2~H4 범위 안에서 구조를 마무리하면 충분합니다.

문단/강조

기본 문단은 설명, 조건, 예외를 자연스럽게 연결하는 데 사용합니다. 한 문단이 너무 길어지면 가독성이 낮아지므로 2~3문장 단위로 나누는 편이 좋습니다. 문장은 행동 주체와 결과를 명확히 유지하세요.

굵게 강조는 핵심 키워드나 반드시 확인해야 할 항목에 제한적으로 사용합니다. 기울임은 용어 소개나 보조 맥락에 사용합니다. 취소선은 폐기된 정책이나 더 이상 권장하지 않는 절차를 표시할 때 유용합니다.

강조를 너무 많이 쓰면 어디가 진짜 중요한지 구별이 어려워집니다. 문단 하나에 굵게 강조는 한두 곳 이내로 제한하는 것이 좋습니다.

링크

링크는 문서 내부 이동과 외부 참조 두 가지 방식으로 사용합니다.

• 내부 링크: [링크 텍스트](/슬러그/) - permalink 값을 그대로 사용합니다.
• 외부 링크: [링크 텍스트](https://example.com) - 새 탭 여부는 렌더러 설정을 따릅니다.

[서식 가이드](/migration-checks/component-basic/)
[Markdown Guide](https://www.markdownguide.org/)

링크 텍스트는 “여기를 클릭” 같은 표현보다 이동 대상이 드러나는 구체적인 표현을 사용하는 것이 좋습니다. 스크린 리더와 SEO 모두에 유리합니다.

이미지

이미지는 문서 폴더 안에 파일을 두고 상대 경로로 참조합니다. title 속성을 지정하면 <figure> 태그 내 <figcaption>으로 렌더링됩니다.

![](./profile_img.png '예시 화면')

이미지 캡션은 화면 용도와 맥락이 드러나도록 작성합니다. “예쁜 화면” 같은 감상형 문구보다 “회원가입 폼 - 이메일 입력 단계”처럼 기능 설명형 문구가 협업과 유지보수에 더 적합합니다.

![[파일명.png]] Obsidian 문법을 사용하면 클릭 시 모달 확대, 파일명 자동 캡션 등 추가 기능을 이용할 수 있습니다. 자세한 내용은 기본 요소 가이드의 이미지 섹션을 참고하세요.

비디오

동영상 파일은 ![[파일명.mp4]] Obsidian 문법으로 삽입합니다. 파일은 문서 폴더 안에 두어야 합니다.

![[test video.mp4]]

mp4를 지정하면 동일 폴더의 .webm 파일을 자동으로 1순위 소스로 추가합니다. WebM을 지원하는 브라우저는 WebM을 우선 재생하고, 그렇지 않은 경우 MP4로 폴백합니다.

test video

인용문

일반 인용문은 > 기호로 작성합니다. 외부 발언을 그대로 옮기거나, 주의가 필요한 내용을 시각적으로 분리할 때 사용합니다.

> 운영 정책은 기능 출시 전후로 조정될 수 있으며, 변경 시에는 문서 이력과 공지 채널을 동시에 갱신해야 합니다.

운영 정책은 기능 출시 전후로 조정될 수 있으며, 변경 시에는 문서 이력과 공지 채널을 동시에 갱신해야 합니다.

강조된 스타일의 인용 컴포넌트가 필요하다면 인터랙티브 컴포넌트 가이드의 :::quote 디렉티브를 사용하세요.

목록

목록은 항목 간 병렬 관계를 나타낼 때 사용합니다. 순서가 없는 목록은 -로, 순서가 있는 절차는 1.으로 작성합니다. 들여쓰기로 중첩 항목을 만들 수 있습니다.

순서 없는 목록

• 신규 기능 등록 - 기능 이름, 담당자, 등록 일시를 함께 기재합니다.
• 영향 범위 점검 - 변경이 미치는 API, 화면, 데이터를 목록으로 정리합니다.
• 배포 전 링크 검증 - 내부 링크와 외부 링크 모두 접속 가능한지 확인합니다.
  • 내부 링크: permalink 값이 실제 문서와 일치하는지 확인
  • 외부 링크: 404 여부와 리다이렉트 유무 점검
    • 리다이렉트가 있는 경우 최종 URL로 교체를 권장합니다.

순서 있는 목록

1. 초안 작성 - 목차를 먼저 잡고 각 섹션의 핵심 문장을 채웁니다.
   1. 프론트매터 작성 및 permalink 확인
2. 리뷰 반영 - 리뷰어 코멘트를 항목별로 처리하고 완료 여부를 표시합니다.
   1. 내용 오류 수정
   2. 표현 및 맞춤법 교정
3. 승인 후 배포 - draft: false로 변경하고 빌드를 실행합니다.
   • 빌드 결과에서 해당 문서 URL 직접 접속 확인
4. 배포 후 재검증 - 실제 사이트에서 이미지, 링크, 레이아웃을 점검합니다.
   1. 모바일 화면 레이아웃 확인
   2. 다크모드 표시 확인

풋노트(각주)

각주는 본문 흐름을 끊지 않으면서 보조 설명이나 출처를 추가할 때 사용합니다.¹ 본문에서 [^키]로 표시하고, 문서 어딘가에 [^키]: 내용으로 정의합니다.²

각주 번호는 본문 참조 순서대로 자동 부여됩니다. 정의 위치와 무관합니다.

본문에서 참조합니다.[^key]

[^key]: 각주 내용은 여기에 작성합니다.

코드

인라인 코드는 짧은 명령, 파일명, 변수명, 설정 값을 표기할 때 사용합니다. 백틱 하나로 감쌉니다.

예: pnpm build, draft: true, permalink

코드블럭은 백틱 세 개로 시작하고 언어를 지정하면 구문 강조가 적용됩니다.

pnpm install
pnpm dev
pnpm build

export type DeployState = 'draft' | 'review' | 'published'

export const nextState = (state: DeployState): DeployState => {
  if (state === 'draft') return 'review'
  if (state === 'review') return 'published'
  return 'published'
}

언어 강조, 줄 하이라이트, 파일명 표시 등 고급 코드블럭 기능은 인터랙티브 컴포넌트 가이드의 코드블럭 섹션을 참고하세요.

표

표는 비교 정보, 옵션 목록, 설정 값 등을 정렬해서 보여줄 때 사용합니다. 마크다운 표는 |로 열을 나누고, 헤더와 본문 사이에 ---를 삽입합니다.

구분	설명	권장값
제목 길이	문서 제목 글자 수	20~45자
설명 길이	메타 설명 글자 수	50~160자
이미지 형식	문서 첨부 이미지	webp 또는 png
코드블럭 언어	언어 미지정 시	txt 또는 text 사용
내부 링크 형식	문서 간 참조	/슬러그/ 형식 사용

열 정렬은 헤더 구분선에 :를 붙여 지정합니다. :---는 왼쪽, ---:는 오른쪽, :---:는 가운데 정렬입니다.

체크리스트

체크박스는 GFM(GitHub Flavored Markdown) 문법으로 작성합니다. - [x]는 완료, - [ ]는 미완료를 나타냅니다. 배포 전 최종 점검 목록이나 작업 진행 상태를 표시할 때 유용합니다.

• 프론트매터 작성 완료 (permalink, title, description, pubDate)
• 제목 계층 확인 (h1 없음, h2부터 시작)
• 이미지 alt/title 작성 및 파일 경로 검증
• 내부 링크 permalink 일치 여부 확인
• 코드블럭 언어 지정 여부 확인
• 모바일 레이아웃 최종 점검
• 배포 후 실제 URL 접속 확인

Footnotes

1. 각주는 핵심 흐름을 방해하지 않으면서 정책 근거나 보조 설명을 추가할 때 가장 유용합니다. ↩

2. 실제 각주 목록 출력은 렌더러 규칙상 문서 하단에 생성됩니다. 정의 위치는 번호 순서에 영향을 주지 않습니다. ↩