Sync docs (#2709)

exercises/practice/acronym/.docs/instructions.md

@@ -10,8 +10,8 @@ Punctuation is handled as follows: hyphens are word separators (like whitespace)
 
 For example:
 
-|Input|Output|
-|-|-|
-|As Soon As Possible|ASAP|
-|Liquid-crystal display|LCD|
-|Thank George It's Friday!|TGIF|
+| Input                     | Output |
+| ------------------------- | ------ |
+| As Soon As Possible       | ASAP   |
+| Liquid-crystal display    | LCD    |
+| Thank George It's Friday! | TGIF   |

exercises/practice/all-your-base/.docs/instructions.md

@@ -14,20 +14,20 @@ Given a number in base **a**, represented as a sequence of digits, convert it to
 
 In positional notation, a number in base **b** can be understood as a linear combination of powers of **b**.
 
-The number 42, *in base 10*, means:
+The number 42, _in base 10_, means:
 
 `(4 * 10^1) + (2 * 10^0)`
 
-The number 101010, *in base 2*, means:
+The number 101010, _in base 2_, means:
 
 `(1 * 2^5) + (0 * 2^4) + (1 * 2^3) + (0 * 2^2) + (1 * 2^1) + (0 * 2^0)`
 
-The number 1120, *in base 3*, means:
+The number 1120, _in base 3_, means:
 
 `(1 * 3^3) + (1 * 3^2) + (2 * 3^1) + (0 * 3^0)`
 
 I think you got the idea!
 
-*Yes. Those three numbers above are exactly the same. Congratulations!*
+_Yes. Those three numbers above are exactly the same. Congratulations!_
 
 [positional-notation]: https://en.wikipedia.org/wiki/Positional_notation

exercises/practice/allergies/.docs/instructions.md

@@ -22,6 +22,6 @@ Now, given just that score of 34, your program should be able to say:
 - Whether Tom is allergic to any one of those allergens listed above.
 - All the allergens Tom is allergic to.
 
-Note: a given score may include allergens **not** listed above (i.e.  allergens that score 256, 512, 1024, etc.).
+Note: a given score may include allergens **not** listed above (i.e. allergens that score 256, 512, 1024, etc.).
 Your program should ignore those components of the score.
 For example, if the allergy score is 257, your program should only report the eggs (1) allergy.

exercises/practice/armstrong-numbers/.docs/instructions.md

@@ -5,9 +5,9 @@ An [Armstrong number][armstrong-number] is a number that is the sum of its own d
 For example:
 
 - 9 is an Armstrong number, because `9 = 9^1 = 9`
-- 10 is *not* an Armstrong number, because `10 != 1^2 + 0^2 = 1`
+- 10 is _not_ an Armstrong number, because `10 != 1^2 + 0^2 = 1`
 - 153 is an Armstrong number, because: `153 = 1^3 + 5^3 + 3^3 = 1 + 125 + 27 = 153`
-- 154 is *not* an Armstrong number, because: `154 != 1^3 + 5^3 + 4^3 = 1 + 125 + 64 = 190`
+- 154 is _not_ an Armstrong number, because: `154 != 1^3 + 5^3 + 4^3 = 1 + 125 + 64 = 190`
 
 Write some code to determine whether a number is an Armstrong number.
 

exercises/practice/binary-search/.docs/instructions.md

@@ -5,13 +5,13 @@ Your task is to implement a binary search algorithm.
 A binary search algorithm finds an item in a list by repeatedly splitting it in half, only keeping the half which contains the item we're looking for.
 It allows us to quickly narrow down the possible locations of our item until we find it, or until we've eliminated all possible locations.
 
-~~~~exercism/caution
+```exercism/caution
 Binary search only works when a list has been sorted.
-~~~~
+```
 
 The algorithm looks like this:
 
-- Find the middle element of a *sorted* list and compare it with the item we're looking for.
+- Find the middle element of a _sorted_ list and compare it with the item we're looking for.
 - If the middle element is our item, then we're done!
 - If the middle element is greater than our item, we can eliminate that element and all the elements **after** it.
 - If the middle element is less than our item, we can eliminate that element and all the elements **before** it.

exercises/practice/book-store/.docs/instructions.md

@@ -36,8 +36,8 @@ This would give a total of:
 
 Resulting in:
 
-- 5 × (100% - 25%) * $8 = 5 × $6.00 = $30.00, plus
-- 3 × (100% - 10%) * $8 = 3 × $7.20 = $21.60
+- 5 × (100% - 25%) × $8 = 5 × $6.00 = $30.00, plus
+- 3 × (100% - 10%) × $8 = 3 × $7.20 = $21.60
 
 Which equals $51.60.
 
@@ -53,8 +53,8 @@ This would give a total of:
 
 Resulting in:
 
-- 4 × (100% - 20%) * $8 = 4 × $6.40 = $25.60, plus
-- 4 × (100% - 20%) * $8 = 4 × $6.40 = $25.60
+- 4 × (100% - 20%) × $8 = 4 × $6.40 = $25.60, plus
+- 4 × (100% - 20%) × $8 = 4 × $6.40 = $25.60
 
 Which equals $51.20.
 

exercises/practice/bowling/.docs/instructions.md

@@ -23,9 +23,9 @@ There are three cases for the tabulation of a frame.
 
 Here is a three frame example:
 
-| Frame 1         | Frame 2       | Frame 3                |
-| :-------------: |:-------------:| :---------------------:|
-| X (strike)      | 5/ (spare)    | 9 0 (open frame)       |
+|  Frame 1   |  Frame 2   |     Frame 3      |
+| :--------: | :--------: | :--------------: |
+| X (strike) | 5/ (spare) | 9 0 (open frame) |
 
 Frame 1 is (10 + 5 + 5) = 20
 

exercises/practice/circular-buffer/.docs/instructions.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 -->
-    [ ][ ][ ][ ][ ][ ][ ]
+
+```text
+[ ][ ][ ][ ][ ][ ][ ]
+```
 
 Assume that a 1 is written into the middle of the buffer (exact starting location does not matter in a circular buffer):
-<!-- prettier-ignore -->
-    [ ][ ][ ][1][ ][ ][ ]
+
+```text
+[ ][ ][ ][1][ ][ ][ ]
+```
 
 Then assume that two more elements are added — 2 & 3 — which get appended after the 1:
-<!-- prettier-ignore -->
-    [ ][ ][ ][1][2][3][ ]
+
+```text
+[ ][ ][ ][1][2][3][ ]
+```
 
 If two elements are then removed from the buffer, the oldest values inside the buffer are removed.
 The two elements removed, in this case, are 1 & 2, leaving the buffer with just a 3:
-<!-- prettier-ignore -->
-    [ ][ ][ ][ ][ ][3][ ]
+
+```text
+[ ][ ][ ][ ][ ][3][ ]
+```
 
 If the buffer has 7 elements then it is completely full:
-<!-- prettier-ignore -->
-    [5][6][7][8][9][3][4]
+
+```text
+[5][6][7][8][9][3][4]
+```
 
 When the buffer is full an error will be raised, alerting the client that further writes are blocked until a slot becomes free.
 
 When the buffer is full, the client can opt to overwrite the oldest data with a forced write.
 In this case, two more elements — A & B — are added and they overwrite the 3 & 4:
-<!-- prettier-ignore -->
-    [5][6][7][8][9][A][B]
+
+```text
+[5][6][7][8][9][A][B]
+```
 
 3 & 4 have been replaced by A & B making 5 now the oldest data in the buffer.
 Finally, if two elements are removed then what would be returned is 5 & 6 yielding the buffer:
-<!-- prettier-ignore -->
-    [ ][ ][7][8][9][A][B]
+
+```text
+[ ][ ][7][8][9][A][B]
+```
 
 Because there is space available, if the client again uses overwrite to store C & D then the space where 5 & 6 were stored previously will be used not the location of 7 & 8.
 7 is still the oldest element and the buffer is once again full.
-<!-- prettier-ignore -->
-    [C][D][7][8][9][A][B]
+
+```text
+[C][D][7][8][9][A][B]
+```

exercises/practice/darts/.docs/instructions.md

@@ -6,6 +6,8 @@ Write a function that returns the earned points in a single toss of a Darts game
 
 In our particular instance of the game, the target rewards 4 different amounts of points, depending on where the dart lands:
 
+![Our dart scoreboard with values from a complete miss to a bullseye](https://assets.exercism.org/images/exercises/darts/darts-scoreboard.svg)
+
 - If the dart lands outside the target, player earns no points (0 points).
 - If the dart lands in the outer circle of the target, player earns 1 point.
 - If the dart lands in the middle circle of the target, player earns 5 points.
@@ -16,8 +18,14 @@ Of course, they are all centered at the same point — that is, the circles are
 
 Write a function that given a point in the target (defined by its [Cartesian coordinates][cartesian-coordinates] `x` and `y`, where `x` and `y` are [real][real-numbers]), returns the correct amount earned by a dart landing at that point.
 
+## Credit
+
+The scoreboard image was created by [habere-et-dispertire][habere-et-dispertire] using [Inkscape][inkscape].
+
 [darts]: https://en.wikipedia.org/wiki/Darts
 [darts-target]: https://en.wikipedia.org/wiki/Darts#/media/File:Darts_in_a_dartboard.jpg
 [concentric]: https://mathworld.wolfram.com/ConcentricCircles.html
 [cartesian-coordinates]: https://www.mathsisfun.com/data/cartesian-coordinates.html
 [real-numbers]: https://www.mathsisfun.com/numbers/real-numbers.html
+[habere-et-dispertire]: https://exercism.org/profiles/habere-et-dispertire
+[inkscape]: https://en.wikipedia.org/wiki/Inkscape

exercises/practice/etl/.docs/instructions.md

@@ -22,6 +22,6 @@ This needs to be changed to store each individual letter with its score in a one
 
 As part of this change, the team has also decided to change the letters to be lower-case rather than upper-case.
 
-~~~~exercism/note
+```exercism/note
 If you want to look at how the data was previously structured and how it needs to change, take a look at the examples in the test suite.
-~~~~
+```

exercises/practice/gigasecond/.docs/introduction.md

@@ -13,12 +13,12 @@ Then we can use metric system prefixes for writing large numbers of seconds in m
 - Perhaps you and your family would travel to somewhere exotic for two megaseconds (that's two million seconds).
 - And if you and your spouse were married for _a thousand million_ seconds, you would celebrate your one gigasecond anniversary.
 
-~~~~exercism/note
+```exercism/note
 If we ever colonize Mars or some other planet, measuring time is going to get even messier.
 If someone says "year" do they mean a year on Earth or a year on Mars?
 
 The idea for this exercise came from the science fiction novel ["A Deepness in the Sky"][vinge-novel] by author Vernor Vinge.
 In it the author uses the metric system as the basis for time measurements.
 
 [vinge-novel]: https://www.tor.com/2017/08/03/science-fiction-with-something-for-everyone-a-deepness-in-the-sky-by-vernor-vinge/
-~~~~
+```

exercises/practice/isbn-verifier/.docs/instructions.md

@@ -1,11 +1,13 @@
 # Instructions
 
-The [ISBN-10 verification process](https://en.wikipedia.org/wiki/International_Standard_Book_Number) is used to validate book identification
-numbers. These normally contain dashes and look like: `3-598-21508-8`
+The [ISBN-10 verification process][isbn-verification] is used to validate book identification numbers.
+These normally contain dashes and look like: `3-598-21508-8`
 
 ## ISBN
 
-The ISBN-10 format is 9 digits (0 to 9) plus one check character (either a digit or an X only). In the case the check character is an X, this represents the value '10'. These may be communicated with or without hyphens, and can be checked for their validity by the following formula:
+The ISBN-10 format is 9 digits (0 to 9) plus one check character (either a digit or an X only).
+In the case the check character is an X, this represents the value '10'.
+These may be communicated with or without hyphens, and can be checked for their validity by the following formula:
 
 ```text
 (d₁ * 10 + d₂ * 9 + d₃ * 8 + d₄ * 7 + d₅ * 6 + d₆ * 5 + d₇ * 4 + d₈ * 3 + d₉ * 2 + d₁₀ * 1) mod 11 == 0
@@ -15,7 +17,8 @@ If the result is 0, then it is a valid ISBN-10, otherwise it is invalid.
 
 ## Example
 
-Let's take the ISBN-10 `3-598-21508-8`. We plug it in to the formula, and get:
+Let's take the ISBN-10 `3-598-21508-8`.
+We plug it in to the formula, and get:
 
 ```text
 (3 * 10 + 5 * 9 + 9 * 8 + 8 * 7 + 2 * 6 + 1 * 5 + 5 * 4 + 0 * 3 + 8 * 2 + 8 * 1) mod 11 == 0
@@ -33,10 +36,7 @@ The program should be able to verify ISBN-10 both with and without separating da
 ## Caveats
 
 Converting from strings to numbers can be tricky in certain languages.
-Now, it's even trickier since the check digit of an ISBN-10 may be 'X' (representing '10'). For instance `3-598-21507-X` is a valid ISBN-10.
+Now, it's even trickier since the check digit of an ISBN-10 may be 'X' (representing '10').
+For instance `3-598-21507-X` is a valid ISBN-10.
 
-## Bonus tasks
-
-* Generate a valid ISBN-13 from the input ISBN-10 (and maybe verify it again with a derived verifier).
-
-* Generate valid ISBN, maybe even from a given starting ISBN.
+[isbn-verification]: https://en.wikipedia.org/wiki/International_Standard_Book_Number

exercises/practice/isogram/.docs/instructions.md

@@ -11,4 +11,4 @@ Examples of isograms:
 - downstream
 - six-year-old
 
-The word *isograms*, however, is not an isogram, because the s repeats.
+The word _isograms_, however, is not an isogram, because the s repeats.

exercises/practice/linked-list/.docs/instructions.md

@@ -13,7 +13,7 @@ Sometimes a station gets closed down, and in that case the station needs to be r
 
 The size of a route is measured not by how far the train travels, but by how many stations it stops at.
 
-~~~~exercism/note
+```exercism/note
 The linked list is a fundamental data structure in computer science, often used in the implementation of other data structures.
 As the name suggests, it is a list of nodes that are linked together.
 It is a list of "nodes", where each node links to its neighbor or neighbors.
@@ -23,4 +23,4 @@ In a **doubly linked list** each node links to both the node that comes before,
 If you want to dig deeper into linked lists, check out [this article][intro-linked-list] that explains it using nice drawings.
 
 [intro-linked-list]: https://medium.com/basecs/whats-a-linked-list-anyway-part-1-d8b7e6508b9d
-~~~~
+```

exercises/practice/list-ops/.docs/instructions.md

@@ -7,13 +7,13 @@ Implement a series of basic list operations, without using existing functions.
 
 The precise number and names of the operations to be implemented will be track dependent to avoid conflicts with existing names, but the general operations you will implement include:
 
-- `append` (*given two lists, add all items in the second list to the end of the first list*);
-- `concatenate` (*given a series of lists, combine all items in all lists into one flattened list*);
-- `filter` (*given a predicate and a list, return the list of all items for which `predicate(item)` is True*);
-- `length` (*given a list, return the total number of items within it*);
-- `map` (*given a function and a list, return the list of the results of applying `function(item)` on all items*);
-- `foldl` (*given a function, a list, and initial accumulator, fold (reduce) each item into the accumulator from the left*);
-- `foldr` (*given a function, a list, and an initial accumulator, fold (reduce) each item into the accumulator from the right*);
-- `reverse` (*given a list, return a list with all the original items, but in reversed order*).
+- `append` (_given two lists, add all items in the second list to the end of the first list_);
+- `concatenate` (_given a series of lists, combine all items in all lists into one flattened list_);
+- `filter` (_given a predicate and a list, return the list of all items for which `predicate(item)` is True_);
+- `length` (_given a list, return the total number of items within it_);
+- `map` (_given a function and a list, return the list of the results of applying `function(item)` on all items_);
+- `foldl` (_given a function, a list, and initial accumulator, fold (reduce) each item into the accumulator from the left_);
+- `foldr` (_given a function, a list, and an initial accumulator, fold (reduce) each item into the accumulator from the right_);
+- `reverse` (_given a list, return a list with all the original items, but in reversed order_).
 
 Note, the ordering in which arguments are passed to the fold functions (`foldl`, `foldr`) is significant.

exercises/practice/pangram/.docs/introduction.md

@@ -7,10 +7,10 @@ To give a comprehensive sense of the font, the random sentences should use **all
 They're running a competition to get suggestions for sentences that they can use.
 You're in charge of checking the submissions to see if they are valid.
 
-~~~~exercism/note
+```exercism/note
 Pangram comes from Greek, παν γράμμα, pan gramma, which means "every letter".
 
 The best known English pangram is:
 
 > The quick brown fox jumps over the lazy dog.
-~~~~
+```

exercises/practice/perfect-numbers/.docs/instructions.md

@@ -1,11 +1,10 @@
 # Instructions
 
-Determine if a number is perfect, abundant, or deficient based on
-Nicomachus' (60 - 120 CE) classification scheme for positive integers.
+Determine if a number is perfect, abundant, or deficient based on Nicomachus' (60 - 120 CE) classification scheme for positive integers.
 
 The Greek mathematician [Nicomachus][nicomachus] devised a classification scheme for positive integers, identifying each as belonging uniquely to the categories of **perfect**, **abundant**, or **deficient** based on their [aliquot sum][aliquot-sum].
 The aliquot sum is defined as the sum of the factors of a number not including the number itself.
-For example, the aliquot sum of 15 is (1 + 3 + 5) = 9
+For example, the aliquot sum of `15` is `1 + 3 + 5 = 9`.
 
 - **Perfect**: aliquot sum = number
   - 6 is a perfect number because (1 + 2 + 3) = 6

exercises/practice/phone-number/.docs/instructions.md

@@ -5,8 +5,8 @@ Clean up user-entered phone numbers so that they can be sent SMS messages.
 The **North American Numbering Plan (NANP)** is a telephone numbering system used by many countries in North America like the United States, Canada or Bermuda.
 All NANP-countries share the same international country code: `1`.
 
-NANP numbers are ten-digit numbers consisting of a three-digit Numbering Plan Area code, commonly known as *area code*, followed by a seven-digit local number.
-The first three digits of the local number represent the *exchange code*, followed by the unique four-digit number which is the *subscriber number*.
+NANP numbers are ten-digit numbers consisting of a three-digit Numbering Plan Area code, commonly known as _area code_, followed by a seven-digit local number.
+The first three digits of the local number represent the _exchange code_, followed by the unique four-digit number which is the _subscriber number_.
 
 The format is usually represented as
 

exercises/practice/protein-translation/.docs/instructions.md

@@ -29,16 +29,16 @@ Note the stop codon `"UAA"` terminates the translation and the final methionine
 
 Below are the codons and resulting Amino Acids needed for the exercise.
 
-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
+| 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          |
 
 Learn more about [protein translation on Wikipedia][protein-translation].
 

exercises/practice/resistor-color-trio/.docs/instructions.md

@@ -23,7 +23,7 @@ For this exercise, you need to know only three things about them:
 - Grey: 8
 - White: 9
 
-In `resistor-color duo` you decoded the first two colors.
+In Resistor Color Duo you decoded the first two colors.
 For instance: orange-orange got the main value `33`.
 The third color stands for how many zeros need to be added to the main value.
 The main value plus the zeros gives us a value in ohms.

exercises/practice/rna-transcription/.docs/instructions.md

@@ -15,6 +15,6 @@ Given a DNA strand, its transcribed RNA strand is formed by replacing each nucle
 - `T` -> `A`
 - `A` -> `U`
 
-~~~~exercism/note
+```exercism/note
 If you want to look at how the inputs and outputs are structured, take a look at the examples in the test suite.
-~~~~
+```