🧪 Integrate pymarkdown into pre-commit config

[webknjaz]

This is meant to ensure consistency in our Markdown content source.

Ref: https://pymarkdown.rtfd.io

Contributor checklist

• Included tests for the changes.
• A change note is created in changelog.d/ (see changelog.d/README.md for instructions) or the PR text says "no changelog needed".

Maintainer checklist

• If no changelog is needed, apply the skip-changelog label.
• Assign the PR to an existing or new milestone for the target version (following Semantic Versioning).

[Copilot]

Pull Request Overview

This PR adds PyMarkdown as a pre-commit hook to the repository for Markdown linting. This will help maintain consistent Markdown formatting and quality across documentation files.

• Added PyMarkdown pre-commit hook configuration

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sirosen]

👍 for the idea of adding this hook -- I didn't know about this tool until today! -- but it looks like we have a number of fixes we need to apply for it to run cleanly.

Some of these are easy and I'm happy to help apply (e.g., max line length) but some appear to be inappropriate lints for the specific files (e.g., MD041 on the changelog dir). How do we want to manage the configuration for this tool such that it's differentiated by file? I'm trying to read the pymarkdown docs but it's not very clear to me what the best approach would be.

[webknjaz]

👍 for the idea of adding this hook -- I didn't know about this tool until today! -- but it looks like we have a number of fixes we need to apply for it to run cleanly.

Yep. I learned about it from a dep bump in ansible-core's test tooling and thought I'd try it locally. But since it produced a bunch of violations, I just made a commit and made the PR draft so that it's out in the open and isn't forgotten on my machine.

Some of these are easy and I'm happy to help apply (e.g., max line length) but some appear to be inappropriate lints for the specific files (e.g., MD041 on the changelog dir). How do we want to manage the configuration for this tool such that it's differentiated by file? I'm trying to read the pymarkdown docs but it's not very clear to me what the best approach would be.

I haven't gotten that far but I'd maybe have two entries in the pre-commit config and include/exclude files on that level if there's no native way to solve this.

[webknjaz]

There's some mentions of selective document set rules @ https://pymarkdown.rtfd.io/en/latest/advanced_configuration/#general-plugin-settings but I'd need to read more for specific examples.

[webknjaz]

@sirosen I fixed a bunch of straightforward violations, need to start looking into suppressions.

[webknjaz]

@sirosen ^

[webknjaz]

@sirosen ^

[webknjaz]

@sirosen ^

[webknjaz]

So apparently, this linter has two docs folders and the one published to RTD doesn't have any mentions of the default config file name. But I've scanned the repo and found that it actually supports a .pymarkdown.yml since jackdewinter/pymarkdown#748: https://github.com/jackdewinter/pymarkdown/blob/main/docs/advanced_configuration.md#default-configuration-files

[webknjaz]

This will need to be replaced once upstream supports disabling rules per-file: jackdewinter/pymarkdown#1511.

[webknjaz]

I filed an upstream feature request to unblock us: jackdewinter/pymarkdown#1511.

[webknjaz]

So apparently, this linter has two docs folders and the one published to RTD doesn't have any mentions of the default config file name. But I've scanned the repo and found that it actually supports a .pymarkdown.yml since jackdewinter/pymarkdown#748: https://github.com/jackdewinter/pymarkdown/blob/main/docs/advanced_configuration.md#default-configuration-files

Turns out, there's a mention in some addition docs site: https://application-properties.rtfd.io/en/latest/file-types/#default-configuration-files (linked from https://pymarkdown.rtfd.io/en/latest/advanced_pre-commit/#specifying-a-configuration-file).

[webknjaz]

Their dogfooding just runs the linter multiple times against different sets of files: https://github.com/jackdewinter/pymarkdown/blob/5d2572d026ff4db21d92d196fd4b69ab7b23fdb5/.pre-commit-config.yaml#L139-L162.

Since the upstream is still unresponsive, I think I'll implement that as a workaround.

[webknjaz]

@sirosen no-emphasis-as-heading is triggered by dates we have in italics. I wonder if wrapping them with <time> would solve this... Doing this causes a no-inline-html. We'll need to decide what to do with that.

[webknjaz]

@sirosen I think this now has all the minimum changes needed to get it merged in.