eslint-plugin-mark

Appearance

heading-id

🔧 Fixable ⭐ CommonMark 🌟 GFM

🔗 Rule Source 🔗 Test Source

Enforce the use of heading IDs.

Rule Details ​

Some Markdown parsers or plugins, like @mdit/plugin-attrs, support custom heading IDs which can be used to add IDs to headings.

Heading IDs are helpful for linking to specific sections within a document and are supported by some websites and markdown parsers through the {#id} syntax. These IDs not only provide improved accessibility, allowing screen readers to create a navigable table of contents, but also enhance SEO by helping search engines understand the structure of the document and deliver better search results.

When building websites with internationalization in mind, it's recommended to use English words for heading IDs. This is because certain languages may cause issues with URL encoding, leading to characters like %20 or %C3%A9 when IDs are encoded, which can make it difficult for people to recognize.

Examples ​

❌ Incorrect ​

Examples of incorrect code for this rule:

Default ​

md
# Heading 1 ⁡

## Heading 2 ⁡

### Heading 3 ⁡

#### Heading 4 ⁡

##### Heading 5 ⁡

###### Heading 6 ⁡

# Heading {#} ⁡

# Heading { #id} ⁡
js
export default [
  // ...
  {
    rules: {
      'mark/heading-id': 'error', 
    },
  },
  // ...
];

✅ Correct ​

Examples of correct code for this rule:

Default ​

md
# Heading 1 {#heading-1}

## Heading 2 {#heading-2}

### Heading 3 {#heading-3}

#### Heading 4 {#heading-4}

##### Heading 5 {#heading-5}

###### Heading 6 {#heading-6}
js
export default [
  // ...
  {
    rules: {
      'mark/heading-id': 'error', 
    },
  },
  // ...
];

Options ​

js
'mark/heading-id': [
  'error',
  'always',
  {
    leftDelimiter: '{',
    rightDelimiter: '}',
    ignoreDepth: [],
  }
]

First Option ​

'always' | 'never' ​

Default: 'always'

'always' enforces the presence of heading IDs. 'never' disallows heading IDs.

Second Option ​

leftDelimiter ​

Default: '{'

WARNING

Please note that if you use a custom delimiter, it must be escaped since it is used in a regular expression. For example, if you want to use '[', you should pass '\\[' to the option.

The left delimiter to use for heading IDs.

rightDelimiter ​

Default: '}'

WARNING

Please note that if you use a custom delimiter, it must be escaped since it is used in a regular expression. For example, if you want to use ']', you should pass '\\]' to the option.

The right delimiter to use for heading IDs.

ignoreDepth ​

Default: []

An array of heading depths to ignore. For example, [1, 2] would ignore the first and second level headings.

AST ​

This rule applies only to the Heading node.

Prior Art ​