마크다운 문서 주석 제거 공식과 빌드 타임 주석 스트리핑 규칙

직접 해보기 →

깃허브(GitHub)의 오픈소스 리드미(README.md) 파일을 다듬거나 기술 문서 번역을 공동 작업하다 보면, 외부에 노출하고 싶지 않은 내부 메모용 개발 비망록이나 번역 참고용 가이드 문장들을 마크다운(Markdown) 주석 규격으로 감추어 기재해 두는 경우가 많습니다.

하지만 최종 배포판(Static Build)을 만들어 배포 배포하거나, 일반 독자에게 마크다운 문서를 온전히 배포하는 시점에는 이러한 내부용 마크다운 HTML 주석이 텍스트 소스 상에 그대로 노출되어 있는 것은 기업 보안 및 문서 무결성 면에서 좋지 않습니다. 본 글에서는 마크다운 문서 내부의 HTML 주석을 말끔히 날려버리는 정규표현식 매핑 공식과 유의점을 해설합니다.

---

1. 마크다운 HTML 주석 탐지 및 제거 정규식 공식

마크다운 스펙에서 공식적으로 수용되는 표준 주석 형태는 HTML과 동일한 <!-- 주석 내용 --> 구조를 차용합니다. 이를 문서 텍스트 전체에서 오차 없이 탐색하여 도려내기 위한 치환 매핑 공식은 다음과 같습니다:

[ S_{\text{cleaned}} = S_{\text{original}}.\text{replace}(P_{\text{comment}}, \text{""}) ]

① 표준 단일행 및 다중행 HTML 주석 제거 정규식 패턴:

[ P_{\text{comment}} = \text{//g} ] 이 수식에서 <!--과 -->은 주석의 경계를 명시하며, [\s\S]*? 패턴은 개행 문자(\s)와 비개행 문자(\S) 전체를 아울러 주석 내부에 개행(줄바꿈)이 포함되어 있는 다중행 주석까지 모조리 커버하며, 뒤에 붙은 물음표(?)는 비탐욕적(Non-greedy) 방식으로 작동하여 여러 주석 블록이 문서 내에 흩어져 있을 때 첫 번째 주석의 시작점부터 맨 마지막 주석의 끝마침표까지 통째로 한 번에 날아가는 오작동을 차단합니다.

---

2. 마크다운 컴파일러 연동 빌드 라이프사이클

실무 개발 프로젝트에서는 마크다운을 빌드하여 HTML 웹페이지로 익스포트하는 Webpack 빌드 타임 라이프사이클(Build Lifecycle)에 이 주석 주석 스트리핑(Stripping) 프로세스를 확실히 연동해 줍니다.

// Next.js 나 static site generator 의 마크다운 파이프라인 내부 예시
function markdownLoader(content) {
  // 컴파일 단계 진입 직전에 HTML 주석을 깨끗하게 우선 제거하여 
  // 번들 크기 축소 및 마크업 보안 무결성을 확보합니다.
  const cleanContent = content.replace(/<!--[\s\S]*?-->/g, "");
  return marked.parse(cleanContent);
}

[!NOTE] 매번 에디터에서 찾기(Ctrl+F) 메뉴를 열어 눈으로 확인해 가며 지우거나 깃에 업로드하기 전 수동 검사를 할 필요 없이, 마크다운 주석 제거기 도구를 활용하면 원문 텍스트를 기입하는 즉시 모든 은닉형 주석 블록들만 정밀 제거한 결과 코드를 1초 만에 복사하여 획득할 수 있습니다.

---

3. 주석 제거 조작 시 발생하기 쉬운 예외 주의사항

1. 마크다운 코드 블록(Code Block) 내부의 주석 보존: 개발자가 마크다운 문서 내부에 예제 예제용 소스 코드 블록을 작성하며 <!-- 같은 문자열을 본문에 삽입했을 경우, 무조건 정규식으로 지우면 예제 코드 일부가 손실되는 참사가 일어납니다. 따라서 이메일 본문이나 개발 예제 블록이 있는 경우에는 코드 블록 영역(\```)을 파싱으로 우선 임시 변수 격리한 뒤 주석 제거를 돌리고 최종 환원해 주어야 안전합니다.
2. Jekyll / Astro 등의 Front Matter 충돌 방지: 마크다운 문서 최상단에 은밀하게 기재하는 YAML 형식의 프론트 메타데이터 속성(--- ...) 정보도 정규식 범위와 혼란을 일으키지 않도록 줄 단위 검사를 병행하는 로직을 거치는 편이 무결성 확보에 절대적입니다.