Set up prettier for markdown files

exercism / problem-specifications

Shared metadata for exercism exercises.

MIT License

326 stars 541 forks source link

Set up prettier for markdown files #2321

Closed angelikatyborska closed 11 months ago

angelikatyborska commented 12 months ago

On Discord, @siebenschlaefer suggested to format the table in the acronym instructions because it's hard to read when you only read the markdown source.

That got me thinking - why do we not have prettier set up here to check formatting of all markdown files? We have it for JSON files.

Are there any unforeseen consequences? I see maybe two:

A lot of files will get changed when initially run (currently seeing 36 files)
~~~~exercism/note will get changed to ```exercism/note - is that a problem?

I was also surprised not to find any evidence of having discussed this issue before in this repository... did I miss something?

If this is a desired change, I could work on it.

iHiD commented 12 months ago

A lot of files will get changed when initially run (currently seeing 36 files)

I'm fine with this.

~~~~exercism/note will get changed to ```exercism/note - is that a problem?

Yes, this is likely a problem, as three-tildes are often nested inside of four wavy things (~). Can we get prettier to skip this one?

If this is a desired change, I could work on it.

It feels great to me. Especially the tables one. Thank you and @siebenschlaefer. As always, I defer my "official" opinion to @ErikSchierboom on problem-spec matters though.

angelikatyborska commented 12 months ago

It would be possible to add a  comment in front of every quadruple-tilde admonition. That would prevent changing quadruple tildes to triple backticks, but also it would prevent any autoformatting in the content of the admonition.

Unfortunately prettier does not offer a lot of configuration options. I'm not sure if you could set up a global "do not autoformat codeblock formatting characters" rule.

iHiD commented 12 months ago

Hmmm, this might be why we've never done it then (the lack of config options)

iHiD commented 12 months ago

Btw:

Old discussion on tildes vs prettier: https://github.com/exercism/problem-specifications/pull/2255
Old PR for Prettier: https://github.com/exercism/problem-specifications/pull/1754

ErikSchierboom commented 12 months ago

It would be possible to add a comment in front of every quadruple-tilde admonition. That would prevent changing quadruple tildes to triple backticks, but also it would prevent any autoformatting in the content of the admonition.

We'd have to strip them on the website side to not have these comments be in the markdown for students. An alternative approach is something similar to what we do with JSON files, where we have a post-processing script to fix JSON arrays: https://github.com/exercism/problem-specifications/blob/main/bin/format-array.rb

ErikSchierboom commented 12 months ago

Yes, this is likely a problem, as three-tildes are often nested inside of four wavy things (~). Can we get prettier to skip this one?

Why is that a problem?

angelikatyborska commented 12 months ago

I think prettier is smart enough to avoid problems. Given this code:

~~~~exercism/note

foo bar

~~~~

It reformats it to:

````exercism/note
```
foo bar
```
````

So it changes a quadruple tilde to a quadruple backtick in case there is a triple backtick inside. Is a quadruple backtick acceptable to all the markdown rendering software that touches problem specs?

I see there were some bugs in https://github.com/exercism/problem-specifications/pull/1754 - I'll look out for those.

ErikSchierboom commented 12 months ago

So it changes a quadruple tilde to a quadruple backtick in case there is a triple backtick inside. Is a quadruple backtick acceptable to all the markdown rendering software that touches problem specs?

Yes I'm positive it is, as far as our code goes, it is still "just" a code block