[Tidy] Apply mdformat to markdown files

[antonymilne]

Description

Initial step towards #719 which actually formats very little of our code and instead applies a general markdown linter across our whole repo. Code formatting will follow in a later PR.

I have played around with various mdformat options and plugins for quite a long time now and I still do not fully understand how it behaves, which make me feel a bit uneasy... But it did help catch several errors in our yaml and seems to have done a generally good job tidying things up.

The most controversial change (which is responsible for 90% of the diff) is that I set keep=no to remove word wrapping. This is something I've wanted to do for a long time (just use word wrapping in your editor with whatever width you like) but I am not strongly wedded to it if others disagree. wdyt @stichbury?

What needs to done still in this PR:

• work out why custom-components.md doesn't get formatted @stichbury
• fix FIXME points @stichbury
• fix links on faq.md @stichbury
• check through the actual built documentation @stichbury (note this can be done without manually looking through every page by generating the html and then doing a diff compared to the current version)
• check Python code formatting @antonymilne

Follow up work:

• apply mdformat-ruff or mdformat-black or blacken-docs (preference is in that order), ideally with good line length @antonymilne. Needs to work for {.python} code blocks

Notice

• I acknowledge and agree that, by checking this box and clicking "Submit Pull Request":

  • I submit this contribution under the Apache 2.0 license and represent that I am entitled to do so on behalf of myself, my employer, or relevant third parties, as applicable.
  • I certify that (a) this contribution is my original creation and / or (b) to the extent it is not my original creation, I am authorized to submit this contribution on behalf of the original creator(s) or their licensees.
  • I certify that the use of this contribution as authorized by the Apache 2.0 license does not violate the intellectual property rights of anyone else.
  • I have not referenced individuals, products or companies in any commits, directly or indirectly.
  • I have not added data or restricted code in any commits, directly or indirectly.

[github-actions]

View the example dashboards of the current commit live on PyCafe ☕ 🚀

Updated on: 2024-11-14 11:01:34 UTC
Commit: 3c78977

Link: vizro-core/examples/dev/

Link: vizro-core/examples/scratch_dev

Link: vizro-core/examples/visual-vocabulary/

Link: vizro-ai/examples/dashboard_ui/

[antonymilne]

@stichbury I don't massively mind these being wrapped but it is a bit unreadable compared to before. If it's possible to fix without changing how they actually render on the github page then that would be great. Otherwise it's ok how it is. I made the same comment in a few places but may well have missed some.

[antonymilne]

Looks like we might need to disable prettier for md files if it conflicts with this. That's easy to do but let's see where mdformat and prettier disagree first.