🧪 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.