마크다운에는 주석 문법이 없습니다
코드처럼 "화면엔 안 보이고 원문에만 남는 메모"를 마크다운 자체 문법으로는 만들 수 없습니다. 마크다운 명세에 주석이라는 개념이 아예 없기 때문입니다. 대신 HTML 주석을 빌려 씁니다.
HTML 주석 <!-- -->
<!--와 --> 사이의 내용은 렌더링되지 않습니다. HTML을 처리하는 대부분의 마크다운 환경에서 동작합니다.
<!-- 이 줄은 화면에 안 보입니다. 작성용 메모. -->
본문은 정상적으로 보입니다.
여러 줄도 됩니다.
<!--
임시로 숨겨둔 문단.
나중에 다시 살릴 예정.
-->
⚠️ 주석은 '숨김'이지 '삭제'가 아닙니다
이 글에서 가장 중요한 부분입니다. 주석 안의 내용은 화면에 안 보일 뿐, 원문에는 그대로 남아 있습니다.
- GitHub의 공개 저장소라면 파일을 열어보는 누구나 읽을 수 있습니다
- 웹 페이지로 발행되면 브라우저의 "페이지 소스 보기"에 그대로 나옵니다
- Git 히스토리에 남으면 나중에 지워도 과거 커밋에서 복원됩니다
그래서 주석에 다음과 같은 것을 넣으면 안 됩니다.
- API 키, 비밀번호, 토큰
- 아직 공개하면 안 되는 일정이나 가격
- 특정 인물에 대한 평가나 내부 논의
- 초안 단계의 민감한 표현
"어차피 안 보이니까 일단 여기 적어두자"는 생각이 사고로 이어지는 전형적인 경로입니다. 보이지 않는 것과 없는 것은 다릅니다. 정말 남으면 안 되는 내용은 주석이 아니라 아예 지우고, 별도의 비공개 메모에 적어두세요.
⚠️ 주석 안에 --를 쓰면 안 됩니다
HTML 주석 규격상 주석 내부에 하이픈 두 개(--)가 연속으로 들어가면 안 됩니다. 실제로는 관대하게 처리하는 브라우저가 많지만, 엄격한 파서에서는 주석이 엉뚱한 위치에서 끊깁니다.
<!-- 이건 위험합니다 -- 이 지점에서 깨질 수 있음 -->
메모에 구분선을 넣고 싶다면 하이픈 대신 다른 기호를 쓰거나 한 개만 쓰세요. 특히 명령줄 옵션(--force, --save-dev 같은)을 주석에 적을 때 무심코 걸립니다.
HTML이 막힌 곳을 위한 대안
드물게 HTML 주석조차 그대로 노출되는 환경이 있습니다. 이럴 때 쓰는 우회법이 링크 정의를 이용한 트릭입니다.
[//]: # (이 줄도 화면에 보이지 않습니다)
원리는 이렇습니다. 마크다운에는 "링크 정의"라는 문법이 있어서, [라벨]: 주소 형태로 링크를 미리 선언해둘 수 있습니다. 선언만 하고 본문에서 그 라벨을 쓰지 않으면 화면에는 아무것도 나오지 않습니다. [//]라는 쓰이지 않을 라벨에 아무 내용이나 붙여두는 것이 이 트릭입니다.
다만 제약이 있습니다.
- 여러 줄을 한 번에 감쌀 수 없습니다. 줄마다 따로 적어야 합니다
- 앞뒤로 빈 줄이 필요합니다. 문단 중간에 끼우면 그냥 텍스트로 나옵니다
- 괄호가 들어간 내용을 적으면 깨집니다
- 가독성이 나쁩니다
그래서 가능하면 <!-- -->를 먼저 쓰고, 정말 안 될 때만 이 방법을 씁니다.
플랫폼별로 되는 곳과 안 되는 곳
| 환경 | HTML 주석 | 링크 라벨 트릭 |
|---|---|---|
GitHub .md·이슈·PR |
동작 | 동작 |
| 벨로그 | 동작 | 동작 |
| 티스토리 마크다운 모드 | 동작 | 동작 |
| 노션 | 안 됨 (글자 그대로 노출) | 안 됨 |
| Slack·Discord | 안 됨 | 안 됨 |
| 정적 사이트 생성기 | 대체로 동작 | 동작 |
노션과 메신저는 마크다운을 완전히 지원하는 것이 아니라 일부 문법만 흉내 내는 방식이라 주석이 통하지 않습니다. 노션에서 메모를 숨기고 싶다면 토글 블록을 접어두는 편이 현실적입니다.
실제로 이렇게 씁니다
주석은 "안 보이는 메모"라는 설명만으로는 쓸 일이 잘 떠오르지 않습니다. 자주 쓰이는 용도를 적어둡니다.
작성 중 남기는 할 일
## 설치 방법
<!-- TODO: 윈도우 환경 설명 추가할 것 -->
macOS 기준으로 설명합니다.
문서를 다시 열었을 때 어디를 손봐야 하는지 바로 보입니다. TODO: 같은 표시를 붙여두면 나중에 검색으로 한 번에 찾을 수 있습니다.
문단 임시 보류
지우기는 아깝고 지금 내보내기엔 이른 문단을 통째로 감싸둡니다. 나중에 주석 표시만 걷어내면 됩니다.
도구에 보내는 지시
일부 도구는 주석을 명령으로 읽습니다. Prettier에게 이 구간은 포맷하지 말라고 알려주거나,
<!-- prettier-ignore -->
| 일부러 | 정렬 |
|맞추지|않은표|
마크다운 린터의 특정 규칙을 잠시 끄는 식입니다. 이건 주석이 화면에 안 보이면서도 원문에 남는다는 성질을 정확히 활용하는 사례입니다.
자동 생성 구간 표시
목차나 API 문서를 스크립트로 생성할 때, 갱신할 범위를 주석으로 표시해두는 방식이 널리 쓰입니다.
<!-- TOC-START -->
(여기는 자동으로 채워집니다)
<!-- TOC-END -->
숨기는 것과 접는 것
"지금은 안 보였으면 좋겠지만 독자가 원하면 볼 수 있게" 하고 싶다면 주석이 아니라 접기/펼치기가 맞습니다. 주석은 독자가 아예 볼 수 없고, 접기는 클릭하면 열립니다. 긴 로그나 부가 설명은 접기 쪽이 대체로 낫습니다.
정리하면, 마크다운 주석은 <!-- -->가 표준적인 방법이고, HTML이 막힌 특수한 경우에만 링크 라벨 트릭을 씁니다. 그리고 무엇을 쓰든 주석은 감춘 것이지 지운 것이 아니라는 점만은 잊지 마세요.