comark-seo

Comark plugin that analyses Markdown for SEO: headings, links, images, word count and reading time.

Install

pnpm add comark-seo

Requires comark >= 0.4 as a peer dependency.

Usage

import { parseMarkdown } from 'comark'
import seo from 'comark-seo'

const tree = await parseMarkdown(markdown, {
  plugins: [seo({ language: 'fra', readingSpeed: 150 })],
})

console.log(tree.meta.seo)

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | enabled | boolean | true | Set to false to skip the analysis. | | language | 'fra' \| 'eng' | — | Stop words ignored in repeatedWords. None are ignored if unset. | | readingSpeed | number | 200 | Words per minute used for readingTime. |

Result

tree.meta.seo holds the analysis:

{
  content:  { words, readingTime, repeatedWords },
  headings: { count, h1Count, hierarchyValid },
  links:    { count, internal, external, special: { anchor, emails, phone }, invalid },
  images:   { count, missingAlt },
  issues:   [ /* see below */ ]
}

Everything is JSON-serialisable, so tree.meta can be sent in an SSR payload or cached as-is.

content

words counts the text of the document. Fenced blocks and inline code are skipped, so snippets and identifiers do not inflate the count.

readingTime is in minutes, rounded to the nearest minute and never below 1.

repeatedWords lists the words appearing more than once, sorted by descending count, ties broken alphabetically:

[
  { word: 'est', count: 12 },
  { word: 'web', count: 9 },
  { word: 'construire', count: 7 },
]

Set language to drop stop words such as le, de or the from that list.

links

Every link is classified into exactly one bucket:

| Bucket | Matches | | --- | --- | | external | Absolute http(s) URL, or protocol-relative //host | | internal | Any relative path: /guide, ./page.md, ../up.md, page.md | | special.anchor | Starts with # | | special.emails | mailto: | | special.phone | tel: | | invalid | Missing href, or an unsupported scheme such as ftp: or javascript: |

headings

hierarchyValid is false as soon as one level is skipped (for example h2 straight to h4). Every break is still reported individually in issues.

Issues

Each entry in issues is a discriminated union on reason:

| reason | Extra fields | Raised when | | --- | --- | --- | | missing-heading-one | — | The document has no h1 | | multiple-h1 | count | The document has more than one h1 | | heading-hierarchy | from, to | A heading level is skipped | | heading-too-long | from, text | A heading exceeds 60 characters | | invalid-heading | — | A heading tag outside h1–h6 | | missing-alt | src | An image has no alt attribute | | missing-dimensions | src, missing | An image lacks width, height or both | | invalid-link | href | A link uses an unsupported scheme | | missing-url | text | A link has no href |

Heading text is flattened before being measured, so ## A **bold** title is counted in full.

License

MIT © Corentin NELHOMME