숏컷 코드

Markdown는 가볍고 읽기 쉬운 문법입니다.[^1]

[^1]: 자세한 배경 설명이나 출처를 적습니다.

문법

각주는 본문 흐름을 유지하면서 보충 정보를 연결하는 트레이드오프 도구다

각주의 핵심 가치는 분리다. 출처, 예외 조건, 긴 설명을 본문에 인라인으로 넣으면 읽는 흐름이 끊기지만, 각주로 보내면 관심 있는 독자만 문서 하단으로 이동해 읽을 수 있다. 반대로 너무 중요한 정보를 각주로 보내면 독자가 놓칠 위험이 있다. 각주는 "읽지 않아도 본문 이해에 지장이 없는 정보"를 기준으로 판단하는 것이 좋다.

이 API는 안정 버전에서만 사용할 수 있습니다.[^stable]

[^stable]: 베타·실험 버전에서는 응답 형식이 달라질 수 있습니다.

GFM 각주 문법은 CommonMark 표준이 아니라 렌더러 지원 여부를 확인해야 한다

[^id] 형식의 각주는 GitHub Flavored Markdown(GFM)이 지원하는 확장이다. GitHub.com, GitLab, 일부 정적 사이트 빌더(Docusaurus, Obsidian 등)에서는 자동으로 번호가 붙은 링크와 하단 각주 섹션이 생성된다. 그러나 CommonMark 표준 파서나 pandoc 기본 설정에서는 인식되지 않아 [^1] 같은 문자열이 그대로 노출된다. 이식성이 필요하다면 pandoc의 --from=markdown+footnotes 옵션 또는 다른 표기 방식을 사용해야 한다.

이 프로젝트는 실험 기능을 포함합니다.[^beta]

[^beta]: 안정 API가 아니므로 버전 업그레이드 때 동작이 달라질 수 있습니다.

각주 식별자는 의미 있는 이름을 쓰면 유지보수가 쉬워진다

각주 식별자는 숫자([^1])와 문자열([^beta]) 모두 사용 가능하다. 숫자는 순서가 고정되어 있어 문서를 편집할 때 번호를 재정렬해야 하는 불편함이 있다. 의미 있는 키워드 식별자를 쓰면 문서를 재구성할 때 참조와 정의를 쌍으로 찾기 쉬워진다. 렌더링 후 화면에 보이는 번호는 문서 순서에 따라 자동으로 매겨지므로 소스 식별자와 달라도 괜찮다.

<!-- 숫자 식별자: 순서 변경 시 관리 부담 -->
배포 주의사항[^1]과 롤백 절차[^2]를 확인합니다.

<!-- 의미 있는 식별자: 재정렬에 강함 -->
배포 주의사항[^deploy-warn]과 롤백 절차[^rollback]를 확인합니다.

[^deploy-warn]: 배포 전 헬스체크 엔드포인트를 반드시 확인합니다.
[^rollback]: 이전 태그로 `git checkout` 후 재배포합니다.

각주가 많아지면 문서 하단 탐색 비용이 증가한다

각주가 페이지에 10개 이상 등장하면 독자는 본문과 하단을 반복해서 오가야 한다. 이런 경우에는 별도 참고 문서 섹션을 만들거나, 정보를 본문에 직접 통합하거나, 참조형 링크로 대체하는 것이 더 나은 선택일 수 있다. 각주는 어디까지나 보충 채널이지 정보의 주된 전달 경로가 아니다.

실무에서는 "본문에 쓰면 길어 보여서" 중요한 제약까지 각주로 보내는 실수가 잦다. 읽지 않아도 되는 정보만 각주로 보내고, 동작을 바꾸는 경고나 핵심 전제는 본문에 남겨 두는 편이 안전하다.

선택 기준

주의할 점

이 설정은 안전합니다.[^danger]

[^danger]: 잘못 설정하면 데이터가 삭제될 수 있습니다.

이런 경고는 각주로 보내면 너무 늦게 읽힙니다. 독자 행동을 바꾸는 내용이라면 본문이나 경고 박스가 더 적절합니다.