Set up prettier for markdown files

[angelikatyborska]

Resolves #2321

Sorry for the notifications spam by pushing single commits, but I needed to see CI results 😇

I see there's supposed to be a workflow reacting to /format comments, but it didn't work for me.

I see no suspicious reformatting happening by prettier's hands. I think this PR should be safe to merge.

[angelikatyborska]

/format

[ee7]

This PR converted admonitions from 4 tildes to 3 backticks. Was this intended?

According to the Exercism markdown spec, they're supposed to use tildes when possible.

Previously: https://github.com/exercism/problem-specifications/pull/2255

[angelikatyborska]

Yes, it was intended. Customizing prettier is not possible, so keeping tildes would require writing an extra script that undoes prettier's formatting. @ErikSchierboom said it's not necessary and everything will work with triple backticks too.

[meatball133]

I think this topic is very scattered across the community, the usage of tildas and backticks really depends on the track. I think there would be the benefit of actually standardizing across tracks. I dont have any direct leaning on which way to go since both have their advantages and disadvantages, but I think some confusion and inconsistency across the tracks could be fixed if we said this is the way to do it instead of having 2 ways which just makes things confusing.

[ee7]

Yes, it was intended.

Ah, okay. Thanks. I looked through all the comments/commits in this PR, but I hadn't seen the discussion in #2321.

I assume this means that we should consider changing the markdown spec. I've opened https://github.com/exercism/docs/issues/457.

[ee7]

but I think some confusion and inconsistency across the tracks could be fixed if we said this is the way to do it instead of having 2 ways which just makes things confusing.

To fully clear in case there was ambiguity: I was only talking about the Exercism-specific admonitions, rather than syntax for code blocks. But the Exercism markdown spec previously said tildes, so tracks should have been using tildes. But I don't know if it ever made a difference.

Currently there are more with tildes. In a directory that contains every Exercism track repo:

$ rg --files-with-matches '~~~exercism/' | wc -l
88
$ rg --files-with-matches '```exercism/' | wc -l
39

[meatball133]

yes I am aware this is only the exercism specific admonitions.

But the Exercism markdown spec previously said tildes, so tracks should have been using tildes. But I don't know if it ever made a difference.

Yes but various tracks have chosen one over the other, and at least in my view, it creates a weird situation.

[ee7]

it creates a weird situation.

I don't disagree.

But the markdown spec has said "All blocks are written using 4 tildes" for the last 2.5 years. The problem isn't that Exercism didn't pick a side :)

The wording of the below part is bad, though:

(Note: You may also use backticks or other levels of tildes in exceptional circumstances)

My understanding was that this meant "in exceptional circumstances, you may use backticks or other levels of tildes", rather than "use backticks if you want, or other levels of tildes in exceptional circumstances".

But if we cared enough, we could probably make configlet lint complain about whatever syntax is deemed incorrect.

[meatball133]

The problem isn't that Exercism didn't pick a side :)

I think there is a divide across the community, I would even like to drag it so far that it is a divide in the exercism team itself.

What has happened is that both methods have been seen as "acceptable" and thereby they have both spread and have both got grounds in their usage areas.

I don't think it may be that simple. And if 39 repos use the "unofficial" way and 88 use the official way those 88 likely mostly come from practice exercises. Does that hint at least to me that there is at least a decent amount of maintainers who use backticks instead of tildas.

[ee7]

And if 39 repos use the "unofficial" way and 88 use the official way those 88 likely mostly come from practice exercises.

Just as a clarification, rather than trying to make a point: the command was counting files, not repos.

Here's the output without piping to wc -l:

Files with tilde admonitions

```console $ rg --sort path --files-with-matches '~~~exercism/' awk/concepts/fundamentals/about.md awk/concepts/nums-strs/about.md awk/concepts/nums-strs/introduction.md awk/concepts/patterns/about.md awk/concepts/patterns/introduction.md cpp/concepts/booleans/about.md cpp/concepts/booleans/introduction.md cpp/concepts/classes/about.md cpp/concepts/classes/introduction.md cpp/concepts/enums/about.md cpp/concepts/enums/introduction.md cpp/concepts/functions/about.md cpp/concepts/functions/introduction.md cpp/concepts/headers/about.md cpp/concepts/headers/introduction.md cpp/concepts/includes/about.md cpp/concepts/includes/introduction.md cpp/concepts/namespaces/about.md cpp/concepts/numbers/about.md cpp/concepts/switch/about.md crystal/exercises/practice/binary-search/.docs/instructions.md crystal/exercises/practice/etl/.docs/instructions.md crystal/exercises/practice/gigasecond/.docs/introduction.md crystal/exercises/practice/linked-list/.docs/instructions.md crystal/exercises/practice/pangram/.docs/introduction.md crystal/exercises/practice/rational-numbers/.docs/instructions.md crystal/exercises/practice/rna-transcription/.docs/instructions.md crystal/exercises/practice/rna-transcription/.docs/introduction.md crystal/exercises/practice/secret-handshake/.docs/instructions.md crystal/exercises/practice/sieve/.docs/instructions.md elixir/concepts/behaviours/about.md elixir/concepts/behaviours/introduction.md elixir/concepts/bitstrings/introduction.md elixir/concepts/charlists/about.md elixir/concepts/charlists/introduction.md elixir/concepts/genserver/about.md elixir/concepts/genserver/introduction.md elixir/concepts/regular-expressions/introduction.md fortran/exercises/practice/linked-list/.docs/instructions.md fortran/exercises/practice/rna-transcription/.docs/instructions.md fortran/exercises/practice/rna-transcription/.docs/introduction.md fortran/exercises/practice/sieve/.docs/instructions.md gleam/concepts/bit-strings/about.md gleam/concepts/bit-strings/introduction.md gleam/concepts/regular-expressions/about.md gleam/concepts/regular-expressions/introduction.md go/concepts/errors/about.md go/concepts/errors/introduction.md go/concepts/range-iteration/about.md go/concepts/range-iteration/introduction.md go/concepts/regular-expressions/about.md go/concepts/regular-expressions/introduction.md go/concepts/structs/about.md go/concepts/structs/introduction.md jq/concepts/basics/about.md jq/concepts/basics/introduction.md jq/concepts/functions/about.md jq/concepts/functions/introduction.md jq/concepts/numbers/about.md jq/concepts/reduce/about.md jq/concepts/reduce/introduction.md jq/concepts/regular-expressions/about.md jq/concepts/regular-expressions/introduction.md jq/concepts/variables/about.md jq/concepts/variables/introduction.md julia/concepts/integer-introduction/about.md julia/concepts/integer-introduction/introduction.md julia/concepts.wip/boolean-logic/about.md julia/concepts.wip/booleans/about.md julia/concepts.wip/docstrings/about.md julia/concepts.wip/docstrings/introduction.md julia/concepts.wip/if-expressions/introduction.md julia/concepts.wip/iterator-protocol/about.md julia/concepts.wip/iterator-protocol/introduction.md julia/concepts.wip/kwdef/about.md julia/concepts.wip/kwdef/introduction.md julia/docs/INSTALLATION.md php/concepts/booleans/about.md php/concepts/booleans/introduction.md python/concepts/basics/about.md python/concepts/binary-octal-hexadecimal/about.md python/concepts/classes/about.md python/concepts/function-arguments/about.md python/concepts/string-formatting/about.md python/concepts/unpacking-and-multiple-assignment/about.md python/concepts/unpacking-and-multiple-assignment/introduction.md python/docs/TOOLS.md racket/docs/INSTALLATION.md ```

Files with backtick admonitions

```console $ rg --sort path --files-with-matches '```exercism/' cpp/concepts/basics/about.md cpp/concepts/basics/introduction.md crystal/concepts/bools/about.md crystal/concepts/bools/introduction.md crystal/concepts/classes/about.md crystal/concepts/classes/introduction.md crystal/concepts/nil/about.md crystal/concepts/number-types/about.md crystal/concepts/numbers/about.md crystal/concepts/numbers/introduction.md crystal/concepts/return/about.md crystal/concepts/return/introduction.md crystal/concepts/strings/about.md crystal/concepts/strings/introduction.md crystal/exercises/concept/crystal-hunter/.docs/introduction.md crystal/exercises/concept/interest-is-interesting/.docs/instructions.md crystal/exercises/concept/interest-is-interesting/.docs/introduction.md crystal/exercises/concept/johannes-juice-maker/.docs/introduction.md crystal/exercises/concept/party-robot/.docs/introduction.md crystal/exercises/concept/wellingtons-weather-station/.docs/introduction.md fortran/exercises/practice/pangram/.docs/introduction.md fsharp/concepts/tuples/about.md go/concepts/variadic-functions/about.md go/concepts/variadic-functions/introduction.md javascript/concepts/array-transformations/about.md javascript/concepts/classes/about.md javascript/concepts/classes/introduction.md javascript/concepts/dates/about.md javascript/concepts/dates/introduction.md python/concepts/generators/about.md ruby/concepts/basics/about.md ruby/concepts/multiple-assignment-and-decomposition/about.md ruby/concepts/multiple-assignment-and-decomposition/introduction.md swift/concepts/basics/about.md swift/concepts/basics/introduction.md swift/concepts/booleans/about.md swift/concepts/booleans/introduction.md swift/concepts/numbers/about.md swift/concepts/numbers/introduction.md ```

[ee7]

But note that the above commands didn't include most hidden files/directories, so it was mostly docs for concepts.

If we include all hidden files, by adding -uu, the counts are:

$ rg -uu --files-with-matches '~~~exercism/' | wc -l
562
$ rg -uu --files-with-matches '```exercism/' | wc -l
257

So yes, there's widespread usage of both.

[iHiD]

A few late night thoughts:

1. If it's in the spec, we should all adhere to it (Erik and I ~often~ sometimes disagree - but we'll always take a "disagree and commit" approach. If it's in the spec. ambiguity is not ok. If it's not in a spec, ambiguity is ok. That's our approach.
2. I quite dislike 4 in 3 backticks (ie I much preferred outer tildes). That said I much prefer Prettier to not having Prettier, so am happy with the change, so consider this now the official Exercism way of doing it.
3. @ee7 Please update the docs - thank you.
4. All other docs not covered by Problem Specs should be updated to match this too. @ErikSchierboom Maybe a bulk PR?
5. @angelikatyborska Thank you for doing the work - its much appreciated by me!

[ErikSchierboom]

There is still another option: we could do some post-processing after prettier is done to convert from 3 backticks to 4 tildes.

edit: in fact I think I even suggested this somewhere, but then forgot about it 🤦

[ErikSchierboom]

If someone is interested in working on this, we don't need to change anything.

BTW we do something similar when formatting JSON using prettier, where we run this script as post-processing: https://github.com/exercism/problem-specifications/blob/main/bin/format-array.rb

[ErikSchierboom]

I think there is a divide across the community, I would even like to drag it so far that it is a divide in the exercism team itself.

I'd rather we'd not engage in speculation about "divisions" in the Exercism team please.

[iHiD]

There is still another option: we could do some post-processing after prettier is done to convert from 3 backticks to 4 tildes.

Erik and I are discussing this btw. @ee7 hold fire for now on changing the docs.