Skip to content

linked-list: use tildes for admonition, not backticks #2255

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 10, 2023

Conversation

ee7
Copy link
Member

@ee7 ee7 commented Apr 9, 2023

Commit d48e19a added an admonition that used backticks, but every other admonition uses tildes.

From the Exercism Markdown specification:

We support special types of blocks that can be added to documents to pull out commentary that doesn't fit with the main body of the text.

[...]

All blocks are written using 4 tildes, in the form of:

~~~~exercism/note
Content goes here

You can include code:
```ruby
str = "Hello, World"
```
~~~~

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


With this PR, every admonition uses tildes:

$ git rev-parse --short HEAD
84d547a2
$ git grep --break --heading 'exercism/' -- 'exercises/*.md'
exercises/binary:search/instructions.md
8:~~~~exercism/caution

exercises/counter/description.md
5:Please see the discussion in [https://github.com/exercism/problem-specifications/issues/80](https://github.com/exercism/problem-specifications/issues/80)

exercises/etl/instructions.md
25:~~~~exercism/note

exercises/gigasecond/introduction.md
16:~~~~exercism/note

exercises/killer:sudoku-helper/description.md
59:[one-solution-img]: https://media.githubusercontent.com/media/exercism/v3-files/main/julia/killer-sudoku-helper/example1.png
60:[four-solutions-img]: https://media.githubusercontent.com/media/exercism/v3-files/main/julia/killer-sudoku-helper/example2.png
61:[not-possible-img]: https://media.githubusercontent.com/media/exercism/v3-files/main/julia/killer-sudoku-helper/example3.png

exercises/linked:list/instructions.md
16:~~~~exercism/note

exercises/pangram/introduction.md
10:~~~~exercism/note

exercises/rational:numbers/description.md
5:~~~~exercism/note

exercises/rna:transcription/instructions.md
18:~~~~exercism/note

exercises/rna:transcription/introduction.md
7:~~~~exercism/note

exercises/secret:handshake/instructions.md
44:~~~~exercism/note

exercises/sieve/instructions.md
21:~~~~exercism/note

From the Exercism Markdown specification [1]:

    We support special types of blocks that can be added to documents to pull out commentary that doesn't fit with the main body of the text.

    [...]

    All blocks are written using 4 tildes, in the form of:

    ~~~~exercism/note
    Content goes here

    You can include code:
    ```ruby
    str = "Hello, World"
    ```
    ~~~~

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

[1] https://github.com/exercism/docs/blob/8c604214c423/building/markdown/markdown.md#special-blocks-sometimes-called-admonitions
@ee7 ee7 requested a review from a team as a code owner April 9, 2023 15:29
Copy link
Member

@kytrinyx kytrinyx left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ugh, I thought I had fixed all these, and somehow missed this one. Thanks for fixing it.

@SleeplessByte
Copy link
Member

If we don't add the prettier ignore thing, every place this is merged with formatting on or copied, it will break 💔

@ee7
Copy link
Member Author

ee7 commented Apr 9, 2023

If we don't add the prettier ignore thing, every place this is merged with formatting on or copied, it will break 💔

I didn't understand this. Is there something that blocks merging? Please expand.

@BethanyG
Copy link
Member

BethanyG commented Apr 9, 2023

If we don't add the prettier ignore thing, every place this is merged with formatting on or copied, it will break 💔

I didn't understand this. Is there something that blocks merging? Please expand.

If you use prettier to auto-format things (and many tracks have this in place via a special command/comment), it will re-fomat the tildas (~~~) and turn them into backticks (```). To stop this behavior, you need to tell prettier to ignore the block (Markdown specific comment here).

We probably should adjust our documentation as well to point that out to folx who also use prettier locally. I know there have been multiple instances on the Python track where someone has used prettier and I've had to make them go back and re-do the ~~~ blocks (and they've argued with me about it).

edited to add: Conversely, we can change the way we do this and use backticks for admonitions. But I think we chose tildas for parsing reasons.

@ee7
Copy link
Member Author

ee7 commented Apr 10, 2023

My understanding is that we can merge this. This PR just brings us back to the status quo: all 9 other admonitions in this repo use tildes.

If you use prettier to auto-format things (and many tracks have this in place via a special command/comment)

Can the track make prettier ignore files that are synced from prob-specs?

@ee7 ee7 merged commit 904313c into exercism:main Apr 10, 2023
@ee7 ee7 deleted the linked-list-tildes branch April 10, 2023 10:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants