Allow a body heading alongside the front matter title in the markdown linter config

[MariusStorhaug]

Documentation pages that carry both a front matter title: and a body heading fail the Markdown linter shipped with the template.

Request

What is confusing or missing

.github/linters/.markdown-lint.yml has no MD025 entry, so markdownlint applies its default front_matter_title pattern and treats a front matter title: as the document's top-level heading. A page that also opens with # Heading is then reported as having multiple top-level headings.

Both keys are wanted. MkDocs reads the front matter title: for navigation and the page title, and the body heading is what renders on github.com, where front matter is shown as a table rather than a title. Every repository generated from this template inherits the conflict, and the author is pushed toward dropping one of the two — losing either correct site navigation or a readable page on GitHub.

This surfaced in PSModule/Markdown#33, where capability documentation had to have title: stripped from three files to get a green lint run.

What is expected

A page carries a front matter title: and a body # Heading without the linter objecting, the same way the ecosystem's own documentation repository already works. MSXOrg/docs resolved this in its own copy of the same file:

MD025:
  front_matter_title: ""      # Allow a body H1 alongside the front matter title

The template's copy has never picked that up, so the two configurations have drifted.

Acceptance criteria

• A Markdown file with a front matter title: and a body # Heading passes the linter.
• MD025 still reports a genuine second # Heading in the body.
• Repositories generated from the template inherit the fix without further configuration.

---

Technical decisions

Set front_matter_title to empty rather than disabling MD025: An empty pattern stops front matter from being counted as a heading while leaving the rule enforcing what it is for — one top-level heading per document. Disabling MD025 outright would also stop catching a genuinely duplicated # Heading, which is a real defect and not a formatting preference.

Match MSXOrg/docs exactly: The same key, value, and comment, so the two files converge rather than diverging in a second direction. The wider drift between the two configurations — MD013 line length, MD041, MD060 — is visible but out of scope here; this issue fixes the one that blocks authoring.

---

Implementation plan

Configuration

• Add the MD025 block with front_matter_title: "" to .github/linters/.markdown-lint.yml

Verification

• Confirm a file with both a front matter title: and a body # Heading lints clean
• Confirm a file with two body # Heading lines is still reported