코드는 린트하면서 문서는 왜 방치할까요
우리가 자바스크립트나 타입스크립트를 짤 때는 ESLint로 깐깐하게 검사하잖아요. 세미콜론, 안 쓰는 변수, 위험한 패턴 같은 걸 자동으로 잡아주니까요. 그런데 정작 README나 문서 같은 마크다운(Markdown) 파일은 아무도 검사 안 하고 그냥 방치되는 경우가 많거든요. 그러다 보면 깨진 링크, 들쭉날쭉한 제목 단계, 닫히지 않은 코드 블록 같은 게 슬쩍 끼어들어요. 오늘 소개할 도구는 바로 그 마크다운을 ESLint로 검사하게 해주는 플러그인이에요.
어떻게 마크다운을 ESLint가 읽을까
여기서 "잠깐, ESLint는 자바스크립트 린터 아니야?" 하는 의문이 들 텐데요. 맞아요. 그래서 트릭이 필요해요. ESLint는 코드를 그냥 글자로 보는 게 아니라, 먼저 AST(추상 구문 트리, 코드를 나무 구조로 분해한 것)로 바꿔서 검사하거든요. 이 플러그인은 마크다운 전용 파서를 끼워서, 마크다운 문서도 똑같이 트리 구조(이른바 mdast)로 분해해요. 그러면 '제목 노드', '링크 노드', '코드 블록 노드' 식으로 각 요소를 ESLint의 규칙(rule)이 검사할 수 있게 되는 거예요.
사용법도 익숙해요. 최신 ESLint의 플랫 설정(flat config, eslint.config.js) 에 이 플러그인을 추가하고, .md 파일을 검사 대상에 포함시키면 끝이에요. 이미 ESLint를 쓰고 있다면 새 도구를 따로 배울 필요 없이, 같은 명령어 eslint . 한 방으로 코드와 문서를 함께 검사하게 돼요. 이게 생각보다 큰 장점이거든요. 도구가 하나로 통일되면 CI 설정도, 에디터 연동도 단순해지니까요.
어떤 걸 잡아주나요
예를 들면 이런 것들이에요. 마크다운 안에 들어간 코드 블록이 실제로 문법 오류가 있는 자바스크립트인지, 제목이 H1 다음에 바로 H3로 건너뛰진 않았는지, 링크 형식이 깨지진 않았는지 같은 거요. 특히 문서 안의 코드 예시까지 린트할 수 있다는 점이 매력적이에요. README에 적어둔 예제 코드가 사실은 동작 안 하는 코드였다, 같은 민망한 상황을 막아주거든요.
업계 맥락에서 비교해보면
마크다운 린팅 도구가 이게 처음은 아니에요. 오래전부터 markdownlint가 스타일 규칙(줄 길이, 들여쓰기 등)을 잡아주는 표준처럼 쓰여왔고, remark-lint는 remark 생태계 기반으로 플러그인을 조합하는 방식이에요. 그리고 Prettier는 문서 포맷을 자동으로 예쁘게 정렬해주죠. 그럼 이 ESLint 플러그인의 위치는 뭐냐면, "이미 ESLint 생태계에 들어와 있는 팀" 에게 가장 자연스러운 선택지라는 거예요. 새 린터를 또 들이지 않고 기존 ESLint 규칙·플러그인·에디터 통합을 그대로 재활용할 수 있으니까요. 도구를 늘리지 않는 게 곧 유지보수 부담을 줄이는 길이거든요.
한국 개발자에게 주는 시사점
오픈소스를 운영하거나 사내 문서를 깃 저장소에서 관리하는 분이라면 바로 효과를 볼 수 있어요. 요즘은 문서가 제품의 첫인상을 좌우하잖아요. README가 깨져 있으면 라이브러리 신뢰도부터 떨어지거든요. CI 파이프라인에 마크다운 린트를 한 줄 추가해두면, PR 단계에서 깨진 링크나 잘못된 예제를 자동으로 걸러낼 수 있어요. "문서도 코드처럼 검증 대상으로 다룬다"는 문화는 팀 전체의 품질을 한 단계 끌어올려줘요.
마무리
한 줄로 정리하면, 이미 ESLint를 쓰고 있다면 마크다운까지 같은 도구로 묶어 검사하자는 거예요. 도구 하나로 코드와 문서를 함께 지키는 거죠. 여러분 팀은 지금 문서 품질을 어떻게 관리하고 계세요? 혹시 README가 깨진 걸 뒤늦게 발견한 경험이 있다면 댓글로 풀어봐요.
🔗 출처: Hacker News