Set up prettier for markdown files #2322

angelikatyborska · 2023-09-15T07:19:20Z

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 · 2023-09-15T07:31:15Z

/format

exercises/book-store/description.md

angelikatyborska · 2023-09-15T07:42:50Z

exercises/circular-buffer/description.md

@@ -4,39 +4,55 @@ A circular buffer, cyclic buffer or ring buffer is a data structure that uses a

 A circular buffer first starts empty and of some predefined length.
 For example, this is a 7-element buffer:
-<!-- prettier-ignore -->


Removing the comment and reformatting didn't produce any changes. But just to be safe, I'll wrap those in backticks. A 4 space intent is equivalent to backticks, but it's not as clear in its intention.

angelikatyborska · 2023-09-15T08:15:22Z

.markdownlint.jsonc

@@ -4,5 +4,6 @@
    "MD004": "dash", // Prefer hyphens for unordered lists
    "MD013": false,  // Exercism tends to break lines at sentence ends rather than at a column limit
    "MD024": false,  // The format for instructions.md requires  repeated headings, e.g. "Task"
-    "MD048": false   // We want three backticks for codeblocks, but four tildes for special blocks.
+    "MD048": false,  // We want three backticks for codeblocks, but four tildes for special blocks.
+    "MD049": false   // Prettier uses underscores, but not all asterisk emphasis can be correctly replaced by underscores.


I was battling markdownlint in this PR, and then I realized that there's this problem:

- The *n*th number gets multiplied by 10^_(n-1)_.

Prettier didn't reformat *n*th to _n_th and when I tried, it doesn't render correctly in my IDE's markdown renderer. So I am making the assumption that I put in the comment here: it is not possible to have consistent emphasis with underscores because apparently they don't work the same as asterisks?

Guessing that it is not possible to have prettier enforce asterisks only?
(Which would result in uniformity)

What is the intention of *n*th ?
Could it instead be *n*-th, or n-th, or some alternative?

I don't think the emphasis is that important here to be honest

It could easily be backticks too I think

Prettier offers almost zero configuration options, be design. It is not possible to change its emphasis preference to asterisks.

I'll remove the unnecessary emphasis on n and remove this new linter rule.

exercises/book-store/description.md

ErikSchierboom · 2023-09-15T10:28:50Z

exercises/protein-translation/description.md

+| Codon              | Protein       |
+| :----------------- | :------------ |
+| AUG                | Methionine    |
+| UUU, UUC           | Phenylalanine |
+| UUA, UUG           | Leucine       |
+| UCU, UCC, UCA, UCG | Serine        |
+| UAU, UAC           | Tyrosine      |
+| UGU, UGC           | Cysteine      |
+| UGG                | Tryptophan    |
+| UAA, UAG, UGA      | STOP          |


This is so much better!

wolf99

LGTM, just two small (non-blocking) questions

wolf99 · 2023-09-15T11:39:11Z

.github/workflows/ci.yml

@@ -123,6 +123,24 @@ jobs:
          globs: |
            **/*.md

+      - name: Setup nodejs


Nit: Is there a Prettier action that could be used either? It would remove the need to take care of yarn and node setup and maintenance.

There seems to be more than once, but I'm not sure if that's a good idea. Historically, prettier upgrades would change the output. So it's important to use exactly the same prettier version to format the files and then later to verify on CI that they have been formatted. If we use a dedicated prettier action, then we make it harder to use exactly the same prettier version in all places. Most likely changing the prettier version would require both changes to package.json and to the configuration of such github aciton where a specific prettier version could be passed. I'm not saying that's a blocker, it just makes me unsure about choosing such a solution.

ee7 · 2023-09-15T18:55:53Z

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: #2255

angelikatyborska · 2023-09-15T19:03:22Z

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 · 2023-09-15T19:14:30Z

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 · 2023-09-15T19:14:46Z

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 exercism/docs#457.

ee7 · 2023-09-15T19:20:12Z

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 · 2023-09-15T19:29:30Z

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 · 2023-09-15T19:46:29Z

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 · 2023-09-15T19:57:22Z

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 · 2023-09-15T20:05:27Z

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

$  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

$  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 · 2023-09-15T20:48:40Z

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 · 2023-09-20T00:21:26Z

A few late night thoughts:

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.
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.
@ee7 Please update the docs - thank you.
All other docs not covered by Problem Specs should be updated to match this too. @ErikSchierboom Maybe a bulk PR?
@angelikatyborska Thank you for doing the work - its much appreciated by me!

ErikSchierboom · 2023-09-20T06:07:48Z

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 · 2023-09-20T06:20:49Z

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 · 2023-09-20T06:24:36Z

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 · 2023-09-20T11:59:21Z

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.

angelikatyborska added 4 commits September 15, 2023 09:18

Set up formatting markdown files

020c8a4

Put the CI step in the right place

dd3df7c

Install prettier on CI

0ce32d4

Do not lint markdown files in node_modules

61eacb7

angelikatyborska added 2 commits September 15, 2023 09:34

Rename format action

f07e56b

Run format-md

5978b2c

angelikatyborska commented Sep 15, 2023

View reviewed changes

exercises/book-store/description.md Outdated Show resolved Hide resolved

Remove unnecessary prettier-ignore comment

4c21ea6

angelikatyborska commented Sep 15, 2023

View reviewed changes

angelikatyborska added 2 commits September 15, 2023 09:47

Reconfigure markdownlint

f7df897

Fix "fenced code blocks should have a language specified"

0dde98f

angelikatyborska force-pushed the format-markdown-files branch 2 times, most recently from c12b041 to 92559a0 Compare September 15, 2023 07:54

Emphasis cannot be consistent

7468c8a

angelikatyborska force-pushed the format-markdown-files branch from 92559a0 to 7468c8a Compare September 15, 2023 08:13

angelikatyborska commented Sep 15, 2023

View reviewed changes

angelikatyborska marked this pull request as ready for review September 15, 2023 08:16

angelikatyborska requested a review from a team as a code owner September 15, 2023 08:16

ErikSchierboom approved these changes Sep 15, 2023

View reviewed changes

wolf99 approved these changes Sep 15, 2023

View reviewed changes

angelikatyborska added 2 commits September 15, 2023 15:59

Use fancy multiplication sign

604c68b

Remove unnecessary weird emphasis

0967b98

meatball133 approved these changes Sep 15, 2023

View reviewed changes

IsaacG approved these changes Sep 15, 2023

View reviewed changes

angelikatyborska merged commit 435e86a into main Sep 15, 2023

angelikatyborska deleted the format-markdown-files branch September 15, 2023 16:42

ee7 mentioned this pull request Sep 15, 2023

markdown spec: consider changing admonition syntax from tildes to backticks exercism/docs#457

Closed

Uh oh!

Set up prettier for markdown files #2322

Set up prettier for markdown files #2322

Uh oh!

Conversation

angelikatyborska commented Sep 15, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

angelikatyborska commented Sep 15, 2023

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wolf99 Sep 15, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wolf99 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ee7 commented Sep 15, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

angelikatyborska commented Sep 15, 2023

Uh oh!

meatball133 commented Sep 15, 2023

Uh oh!

ee7 commented Sep 15, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ee7 commented Sep 15, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

meatball133 commented Sep 15, 2023

Uh oh!

ee7 commented Sep 15, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

meatball133 commented Sep 15, 2023

Uh oh!

ee7 commented Sep 15, 2023

Uh oh!

ee7 commented Sep 15, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

iHiD commented Sep 20, 2023

Uh oh!

ErikSchierboom commented Sep 20, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ErikSchierboom commented Sep 20, 2023

Uh oh!

ErikSchierboom commented Sep 20, 2023

Uh oh!

iHiD commented Sep 20, 2023

Uh oh!

Uh oh!

angelikatyborska commented Sep 15, 2023 •

edited

Loading

wolf99 Sep 15, 2023 •

edited

Loading

ee7 commented Sep 15, 2023 •

edited

Loading

ee7 commented Sep 15, 2023 •

edited

Loading

ee7 commented Sep 15, 2023 •

edited

Loading

ee7 commented Sep 15, 2023 •

edited

Loading

ee7 commented Sep 15, 2023 •

edited

Loading

ErikSchierboom commented Sep 20, 2023 •

edited

Loading