빠른 비교
| 도구 | 역할 |
|---|---|
| formatter | 줄바꿈, 들여쓰기, 표 간격처럼 표현을 자동 정리 |
| linter | 제목 단계, trailing space, 빈 줄, 링크 규칙 같은 문서 규칙 검사 |
| content audit | 프로젝트 frontmatter, slug, order, MDX 컴포넌트 같은 서비스 규칙 검사 |
역할 구분
format은 모양을 통일하고 lint는 규칙 위반을 찾는다
Markdown formatting은 문서의 시각적 표현을 일관되게 정리하는 작업입니다. Prettier 같은 formatter는 목록 들여쓰기, 표 정렬, 줄바꿈을 자동으로 바꿀 수 있습니다. 반면 markdownlint 같은 linter는 heading 단계가 건너뛰었는지, 같은 제목이 반복되는지, 리스트 주변 빈 줄이 맞는지 같은 규칙 위반을 찾습니다.
npx prettier --write "docs//*.md"
npx markdownlint "docs//*.md"둘은 대체 관계가 아닙니다. formatter가 통과해도 heading 계층이 잘못됐을 수 있고, linter가 통과해도 프로젝트 frontmatter 규칙은 빠질 수 있습니다.
자동 수정 가능 여부를 기준으로 나눈다
공백, 표 정렬, trailing space처럼 정답이 기계적으로 정해지는 문제는 formatter나 linter --fix에 맡기기 좋습니다. 반면 "H1은 문서당 하나만", "링크 텍스트를 의미 있게 쓰기", "heading 단계 건너뛰지 않기" 같은 규칙은 자동 수정이 문서 의미를 망칠 수 있습니다. 자동화는 안전한 규칙부터 적용하고, 의미 판단이 필요한 규칙은 CI에서 실패시키는 정도로 제한하는 편이 낫습니다.
npx markdownlint --fix "docs/**/*.md"자동 수정 후에는 diff를 확인해야 합니다. 특히 표나 MDX가 섞인 문서는 formatter가 줄바꿈을 바꾸면서 가독성이 달라질 수 있습니다.
MDX와 frontmatter는 일반 Markdown보다 검증 범위가 넓다
MDX 문서는 Markdown, JSX, frontmatter가 한 파일에 섞입니다. 일반 Markdown formatter나 linter만으로는 JSX props, import, 커스텀 컴포넌트 사용 규칙, frontmatter 필수 필드를 모두 검증할 수 없습니다. 프로젝트가 MDX를 콘텐츠 원본으로 쓴다면 일반 lint 외에 별도 content audit가 필요합니다.
일반 Markdown 검증
- heading 계층
- 목록 들여쓰기
- 코드 fence
- 링크 형식
프로젝트 콘텐츠 검증
- frontmatter 필수 필드
- slug/order 중복
- 허용된 category
- MDX 컴포넌트 사용 규칙운영 기준
| 상황 | 우선 확인 |
|---|---|
| 저장 전 자동 정리 | formatter |
| PR에서 문서 규칙 확인 | linter |
| 서비스 콘텐츠 등록 전 | content audit |
| MDX 컴포넌트가 포함됨 | MDX parser 기반 검증 |
| 큰 문서 일괄 포맷 | diff 검토 필수 |
주의할 점
formatter를 콘텐츠 품질 검증으로 착각하면 안 됩니다. 줄바꿈과 표 간격이 깔끔해도 frontmatter 누락, 링크 대상 오류, heading 구조 문제, MDX 컴포넌트 오류는 남을 수 있습니다. 자동 포맷은 표현 정리, lint와 audit는 규칙 검증으로 분리하세요.
팀 문서에서는 규칙을 한꺼번에 많이 켜기보다 실제로 유지할 수 있는 규칙부터 적용하는 것이 중요합니다. 너무 엄격한 lint 설정은 문서 기여를 막고, 너무 느슨한 설정은 나중에 일괄 정리 비용을 키웁니다.
참고 링크
2 sources