Markdownlint: Confusing or contradictory rule - expects empty line 1 vs MD041 requiring H1

[konard]

Description

I'm experiencing a contradictory markdown linting issue when using Codacy's markdownlint engine on a GitHub pull request.

The Problem

Codacy is reporting an issue on a markdown file:

• File: FEATURE_COMPARISON.md
• Line: 1
• Error: "Expected: {None}; Actual: # Feature Comparison"
• Category: Best practice

However, this contradicts standard markdown best practice:

• MD041 (first-line-heading) requires files to start with an H1 heading
• All other markdown files in the same repository start with H1 headings and pass Codacy checks

Expected Behavior

Either:

1. Codacy should accept H1 headings on line 1 (consistent with MD041)
2. Or provide clear documentation about why line 1 should be empty

Repository Context

• Repository: https://github.com/linksplatform/Protocols.Lino
• Pull Request: Add feature comparison: YAML vs XML vs JSON vs LINO link-foundation/links-notation#82
• Affected File: FEATURE_COMPARISON.md

All other .md files in the repository (README.md, README.ru.md, etc.) start with H1 headings on line 1 and pass Codacy checks without issues.

Request

Please clarify:

1. Is this expected behavior?
2. Why does this rule differ from standard markdownlint MD041?
3. Should all markdown files have an empty first line, or is this a false positive?

Thank you!

[konard]

Workarounds

I've tried several approaches to resolve this issue:

1. Fixed .codacy.yml Configuration

Changed from exclude_patterns to exclude_paths (proper syntax per Codacy docs):

engines:
  markdownlint:
    enabled: true
    exclude_paths:
      - 'FEATURE_COMPARISON.md'

2. Added .markdownlint.json

Disabled MD041 globally:

{
  "default": true,
  "MD041": false
}

3. Prepared YAML Frontmatter Alternative

Created version with YAML frontmatter (which MD041 allows):

---
title: Feature Comparison
---

(rest of content)