·2분 읽기
마크다운 체크박스 목록 작성법 — GitHub Todo List 실전 문법
마크다운 체크박스 문법과 깃허브·노션·옵시디언 호환 방법을 정리했어요. 중첩 체크리스트, 진행률 표시, 실전 PR 템플릿까지 다뤘습니다.
마크다운 체크박스 기본 문법
GFM(GitHub-Flavored Markdown)에서 체크박스는 간단해요.
- 공백 대괄호 공백 = 미완료 항목
- 대괄호 안에 x = 완료된 항목
대괄호 안의 공백은 미완료, 소문자 x는 완료예요. 대문자 X도 인식되지만 소문자가 관례입니다.
중첩 체크리스트
상위 작업 안에 세부 작업을 넣으려면 들여쓰기를 써요.
예시:
- 프로젝트 셋업 (미완료)
- 저장소 생성 (완료)
- Next.js 설치 (완료)
- ESLint 설정 (미완료)
- 배포 (미완료)
- Cloudflare Pages 연결
- 도메인 연결
들여쓰기는 스페이스 2개 또는 4개가 일반적이에요. 탭은 일부 렌더러에서 깨질 수 있으니 스페이스를 권장합니다.
호환되는 렌더러
체크박스는 GFM 확장 문법이라 모든 마크다운에서 되는 건 아니에요.
지원: GitHub, GitLab, Bitbucket, Notion, Obsidian, Typora, Toolkio Previewer
미지원(기본): 순정 CommonMark, 구버전 Jekyll, 기본 Docusaurus
미지원 환경에서는 HTML input checkbox 태그로 대체해야 해요.
진행률 표시하기
체크된 개수를 자동으로 세서 진행률 뱃지를 달 수 있어요. GitHub Issue·PR에서는 자동으로 3/5 completed 형태 표시가 붙어요.
뱃지를 넣고 싶으면 shields.io 같은 서비스를 써서 진행률 이미지를 삽입할 수 있어요.
마일스톤 체크리스트 60% 같은 형태로 구성하면 진행 상황이 한눈에 들어와요.
실전 PR 템플릿
깃허브 Pull Request 템플릿 예시예요. github 디렉토리 pull_request_template.md에 저장하세요.
- 변경 사항 (요약)
- 체크리스트: 로컬에서 빌드 성공 / 테스트 추가 또는 수정 / 관련 이슈 링크 / 리뷰어 지정 / 스크린샷 첨부 (UI 변경 시)
- 배포 주의사항: 환경 변수 추가 필요 / DB 마이그레이션 필요 / 롤백 계획 준비
매번 같은 체크리스트가 자동 삽입돼서 누락이 줄어요.
Toolkio Markdown Previewer로 확인
체크박스를 작성하면서 바로 렌더링 확인할 수 있어요. GFM 모드를 켜면 체크박스가 활성화된 상태로 표시돼요.
옵시디언처럼 체크 상태를 토글하는 기능은 없지만, 렌더링 결과를 HTML로 복사해서 티스토리·노션에 붙일 때 편해요.