eslint-plugin-markdown-seo

마크다운 파일의 SEO 최적화를 위한 ESLint 플러그인입니다. 블로그 포스트의 Frontmatter, 제목 구조, 이미지, 링크 등을 검증합니다.

설치

npm install --save-dev eslint-plugin-markdown-seo

사용법

ESLint Flat Config (ESLint 9+)

// eslint.config.mjs
import markdownSeo from "eslint-plugin-markdown-seo";

export default [
  {
    files: ["**/*.md"],
    plugins: {
      "markdown-seo": markdownSeo,
    },
    processor: "markdown-seo/markdown",
  },
  {
    files: ["**/*.md.js"],
    plugins: {
      "markdown-seo": markdownSeo,
    },
    rules: {
      // Frontmatter 규칙
      "markdown-seo/require-frontmatter": "error",
      "markdown-seo/frontmatter-title": [
        "error",
        {
          minLength: 10,
          maxLength: 60,
        },
      ],
      "markdown-seo/frontmatter-excerpt": [
        "warn",
        {
          minLength: 100,
          maxLength: 200,
        },
      ],
      "markdown-seo/frontmatter-tags": [
        "warn",
        {
          min: 3,
          max: 5,
        },
      ],
      "markdown-seo/frontmatter-published": "error",

      // 제목 구조 규칙
      "markdown-seo/no-h1-in-content": "error",
      "markdown-seo/heading-hierarchy": "warn",

      // 이미지 규칙
      "markdown-seo/image-alt-text": "error",
      "markdown-seo/image-alt-quality": "warn",

      // 링크 규칙
      "markdown-seo/link-text-quality": "warn",

      // 콘텐츠 품질
      "markdown-seo/min-content-length": ["warn", { min: 300 }],
      "markdown-seo/keyword-optimization": "warn",
    },
  },
];

규칙

Frontmatter 규칙

require-frontmatter

Frontmatter에 필수 필드(title, excerpt, publishedAt, tags)가 있는지 검증합니다.

'markdown-seo/require-frontmatter': 'error'

frontmatter-title

제목의 길이를 검증합니다.

'markdown-seo/frontmatter-title': [
  'error',
  {
    minLength: 10,  // 기본값: 10
    maxLength: 60,  // 기본값: 60
  },
]

frontmatter-excerpt

요약(excerpt)의 길이를 검증합니다. SEO를 위해 150-160자가 권장됩니다.

'markdown-seo/frontmatter-excerpt': [
  'warn',
  {
    minLength: 100,  // 기본값: 100
    maxLength: 200,  // 기본값: 200
  },
]

frontmatter-tags

태그 개수를 검증합니다.

'markdown-seo/frontmatter-tags': [
  'warn',
  {
    min: 3,  // 기본값: 3
    max: 5,  // 기본값: 5
  },
]

frontmatter-published

발행일(publishedAt)의 형식을 검증합니다. YYYY-MM-DD 형식이어야 합니다.

'markdown-seo/frontmatter-published': 'error'

제목 구조 규칙

no-h1-in-content

본문에 H1(# ) 사용을 금지합니다. Frontmatter의 title이 H1 역할을 합니다.

'markdown-seo/no-h1-in-content': 'error'

heading-hierarchy

제목 계층 구조를 검증합니다. H2부터 시작하고 순서를 준수해야 합니다.

'markdown-seo/heading-hierarchy': 'warn'

이미지 규칙

image-alt-text

모든 이미지에 alt 텍스트가 있는지 검증합니다.

'markdown-seo/image-alt-text': 'error'

image-alt-quality

의미 있는 alt 텍스트를 사용하는지 검증합니다. "image", "img", "사진" 같은 의미 없는 텍스트를 경고합니다.

'markdown-seo/image-alt-quality': 'warn'

링크 규칙

link-text-quality

의미 있는 링크 텍스트를 사용하는지 검증합니다. "여기", "클릭", "here" 같은 텍스트를 경고합니다.

'markdown-seo/link-text-quality': 'warn'

콘텐츠 품질

min-content-length

본문의 최소 길이를 검증합니다.

'markdown-seo/min-content-length': ['warn', { min: 300 }]

keyword-optimization

첫 번째 단락에 주요 키워드가 포함되어 있는지 검증합니다.

'markdown-seo/keyword-optimization': 'warn'

예제

올바른 예시

---
title: "블로그 포스트 제목"
excerpt: "이것은 100자 이상의 요약입니다. SEO를 위해 충분한 길이의 요약을 작성하는 것이 중요합니다."
publishedAt: "2025-01-15"
tags: ["블로그", "SEO", "마크다운", "개발"]
---

## 소제목

첫 번째 단락에는 주요 키워드가 포함되어야 합니다.

![의미 있는 이미지 설명](./image.png)

[유용한 링크 텍스트](https://example.com)

잘못된 예시

---
title: "짧음" # ❌ 제목이 너무 짧음
excerpt: "짧음" # ❌ 요약이 너무 짧음
publishedAt: "2025-01-15"
tags: ["태그1"] # ❌ 태그가 너무 적음
---

# 본문 제목 # ❌ H1 사용 금지

![](./image.png) # ❌ alt 텍스트 없음

[여기](https://example.com) # ❌ 의미 없는 링크 텍스트

요구사항

• Node.js >= 14.0.0
• ESLint >= 8.0.0

라이선스

MIT