markdownlint-configuration

What this skill does

# Markdownlint Configuration

Master markdownlint configuration including rule management, configuration files, inline comment directives, style inheritance, and schema validation for consistent Markdown linting.

## Overview

Markdownlint is a Node.js style checker and linter for Markdown/CommonMark files. It helps enforce consistent formatting and style across Markdown documentation by providing a comprehensive set of rules that can be customized through configuration files or inline comments.

## Installation and Setup

### Basic Installation

Install markdownlint in your project:

```bash
npm install --save-dev markdownlint markdownlint-cli
# or
pnpm add -D markdownlint markdownlint-cli
# or
yarn add -D markdownlint markdownlint-cli
```

### Verify Installation

```bash
npx markdownlint --version
```

## Configuration File Structure

### Basic .markdownlint.json

Create a `.markdownlint.json` file in your project root:

```json
{
  "default": true,
  "MD003": { "style": "atx_closed" },
  "MD007": { "indent": 4 },
  "no-hard-tabs": false,
  "whitespace": false
}
```

This configuration:
- Enables all default rules via `"default": true`
- Configures MD003 (heading style) to use ATX closed format
- Sets MD007 (unordered list indentation) to 4 spaces
- Disables the no-hard-tabs rule
- Disables all whitespace rules

### Rule Naming Conventions

Rules can be referenced by their ID (MD###) or friendly name:

```json
{
  "MD001": false,
  "heading-increment": false,
  "MD003": { "style": "atx" },
  "heading-style": { "style": "atx" },
  "no-inline-html": {
    "allowed_elements": ["strong", "em", "br"]
  }
}
```

Both ID and friendly name work identically.

## Configuration Options

### Enable/Disable All Rules

```json
{
  "default": true
}
```

When `"default": false`, only explicitly enabled rules are active:

```json
{
  "default": false,
  "MD001": true,
  "MD003": { "style": "atx" },
  "line-length": true
}
```

### Rule-Specific Parameters

#### Heading Style (MD003)

```json
{
  "heading-style": {
    "style": "atx"
  }
}
```

Options: `"atx"`, `"atx_closed"`, `"setext"`, `"setext_with_atx"`, `"setext_with_atx_closed"`

#### Unordered List Style (MD004)

```json
{
  "ul-style": {
    "style": "asterisk"
  }
}
```

Options: `"asterisk"`, `"dash"`, `"plus"`, `"consistent"`, `"sublist"`

#### List Indentation (MD007)

```json
{
  "ul-indent": {
    "indent": 4,
    "start_indented": true
  }
}
```

#### Line Length (MD013)

```json
{
  "line-length": {
    "line_length": 100,
    "heading_line_length": 120,
    "code_block_line_length": 120,
    "code_blocks": true,
    "tables": false,
    "headings": true,
    "strict": false,
    "stern": false
  }
}
```

#### No Trailing Spaces (MD009)

```json
{
  "no-trailing-spaces": {
    "br_spaces": 2,
    "list_item_empty_lines": false,
    "strict": false
  }
}
```

#### No Inline HTML (MD033)

```json
{
  "no-inline-html": {
    "allowed_elements": [
      "strong",
      "em",
      "br",
      "sub",
      "sup",
      "kbd",
      "details",
      "summary"
    ]
  }
}
```

#### Horizontal Rule Style (MD035)

```json
{
  "hr-style": {
    "style": "---"
  }
}
```

Options: `"---"`, `"***"`, `"___"`, or custom like `"- - -"`

#### First Line Heading (MD041)

```json
{
  "first-line-heading": {
    "level": 1,
    "front_matter_title": ""
  }
}
```

#### Required Headings

```json
{
  "required-headings": {
    "headings": [
      "# Title",
      "## Description",
      "## Examples",
      "## Resources"
    ]
  }
}
```

#### Proper Names (MD044)

```json
{
  "proper-names": {
    "names": [
      "JavaScript",
      "TypeScript",
      "GitHub",
      "markdownlint",
      "npm"
    ],
    "code_blocks": false
  }
}
```

## Inline Configuration Comments

### Disable Rules for Entire File

```markdown
<!-- markdownlint-disable-file -->

# This file has no linting applied

Any markdown content here will not be checked.
```

### Disable Specific Rules for File

```markdown
<!-- markdownlint-disable-file MD013 MD033 -->

# Long lines and HTML are allowed in this file

This line can be as long as you want without triggering MD013.

<div>Inline HTML is also allowed</div>
```

### Disable Rules Temporarily

```markdown
<!-- markdownlint-disable MD033 -->

<div class="custom-block">
  HTML content here
</div>

<!-- markdownlint-enable MD033 -->

Regular markdown content with rules enforced.
```

### Disable for Single Line

```markdown
This line follows all rules.

Long line that exceeds limit <!-- markdownlint-disable-line MD013 -->

This line follows all rules again.
```

### Disable for Next Line

```markdown
<!-- markdownlint-disable-next-line MD013 -->
This is a very long line that would normally trigger the line-length rule but won't because of the comment above.

This line follows normal rules.
```

### Capture and Restore Configuration

```markdown
<!-- markdownlint-capture -->
<!-- markdownlint-disable -->

Any violations allowed here.

<!-- markdownlint-restore -->

Back to original configuration.
```

### Configure Rules Inline

```markdown
<!-- markdownlint-configure-file {
  "line-length": {
    "line_length": 120
  },
  "no-inline-html": {
    "allowed_elements": ["strong", "em"]
  }
} -->

# Document Title

Rest of document follows inline configuration.
```

## Configuration File Formats

### JSON Configuration

`.markdownlint.json`:

```json
{
  "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json",
  "default": true,
  "MD003": { "style": "atx" },
  "MD007": { "indent": 2 },
  "MD013": {
    "line_length": 100,
    "code_blocks": false
  },
  "MD033": {
    "allowed_elements": ["br", "strong", "em"]
  }
}
```

### YAML Configuration

`.markdownlint.yaml`:

```yaml
default: true
MD003:
  style: atx
MD007:
  indent: 2
MD013:
  line_length: 100
  code_blocks: false
MD033:
  allowed_elements:
    - br
    - strong
    - em
```

### JavaScript Configuration

`.markdownlint.js`:

```javascript
module.exports = {
  default: true,
  MD003: { style: "atx" },
  MD007: { indent: 2 },
  MD013: {
    line_length: 100,
    code_blocks: false
  },
  MD033: {
    allowed_elements: ["br", "strong", "em"]
  }
};
```

## Configuration Inheritance

### Extending Base Configurations

Create a base configuration:

`base.json`:
```json
{
  "default": true,
  "line-length": {
    "line_length": 100
  }
}
```

Extend it in your project:

`custom.json`:
```json
{
  "extends": "base.json",
  "no-inline-html": false,
  "line-length": {
    "line_length": 120
  }
}
```

### Using Predefined Styles

Markdownlint includes predefined style configurations:

```json
{
  "extends": "markdownlint/style/relaxed"
}
```

Available styles:
- `markdownlint/style/relaxed` - Less strict rules
- `markdownlint/style/prettier` - Compatible with Prettier

## Schema Validation

### Enable IDE Support

Include the `$schema` property for autocomplete and validation:

```json
{
  "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json",
  "default": true
}
```

This enables:
- Autocomplete for rule names
- Validation of configuration values
- Inline documentation in supported editors

## Project-Specific Configurations

### Per-Directory Configuration

Place `.markdownlint.json` in specific directories:

```
project/
├── .markdownlint.json          # Root config
├── docs/
│   ├── .markdownlint.json      # Docs-specific config
│   └── guides/
│       └── .markdownlint.json  # Guides-specific config
```

### Monorepo Configuration

Root `.markdownlint.json`:

```json
{
  "default": true,
  "line-length": {
    "line_length": 100
  }
}
```

Package-specific `packages/api/docs/.markdownlint.json`:

```json
{
  "extends": "../../../.markdownlint.json",
  "no-inline-html": {
    "allowed_elements": ["code", "pre", "div"]
  }
}
```

## Common Configuration Patterns

### Strict Documentation Standards

```json
{
  "default": tru