Add mdformat to pre-commit

[RobertRosca]

#1183 suggests adding "prettier" markdown formatter to pre-commit/ci, not sure if that means just any formatter to make markdown prettier or specifically the formatter called prettier 😛

This PR:

• Adds the ExecutableBooks Markdown formatter to pre-commit. I chose this instead of prettier as for the reasons mentioned in the 'Why not use prettier instead?' section of their readme
• Adds in a separate pre-commit workflow to execute pre-commit. Personally I prefer having these linting checks in a different workflow to the CI one, as this way the CI will still execute even if there are formatting issues, but I don't have a strong preference
• Makes required changes to existing markdown files (found by running pre-commit run --all)

Closes #1183

[codecov]

Codecov Report

Base: 83.45% // Head: 83.45% // No change to project coverage 👍

Coverage data is based on head (e56b8bd) compared to base (aebcf6a).
Patch has no changes to coverable lines.

❗ Current head e56b8bd differs from pull request most recent head 08d01d0. Consider uploading reports for the commit 08d01d0 to get more accurate results

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1267   +/-   ##
=======================================
  Coverage   83.45%   83.45%           
=======================================
  Files          31       31           
  Lines        4224     4224           
  Branches      620      620           
=======================================
  Hits         3525     3525           
  Misses        523      523           
  Partials      176      176           

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[cooperlees]

Pure python and the other noted reasons are great reasons to use this. Thanks for sharing that this exists!

Lets just workout if we can remove the action or remove pre-commit CI - I think we can ...

[cooperlees]

It seems mdformat also has MyST support. Should we look into this since we use that render our docs?

[RobertRosca]

It seems mdformat also has MyST support. Should we look into this since we use that render our docs?

I added the myst formatter, ran it, and it made a few minor changes to escape curly braces. One of them was in the docs, changing a fence ::{warning} to ::\{warning}, which seemed a bit fishy. I built the docs and that showed some warnings:

writing output... [100%] storage_options                                                                                                                                                 
/home/roscar/work/github.com/RobertRosca/bandersnatch/docs/mirror_configuration.md:114: WARNING: Pygments lexer name '\\{warning}' is not known
/home/roscar/work/github.com/RobertRosca/bandersnatch/docs/mirror_configuration.md:165: WARNING: Pygments lexer name '\\{note}' is not known
generating indices... genindex py-modindex done

There are some issues (executablebooks/mdformat-myst#13) related to this, and it looks like the escaping is expected behaviour. So I'd recommend not adding this formatter in as it will would always attempt to reformat this fence syntax, causing issues with the docs.

[cooperlees]

Awesome then. Thanks for this and digging into everything.