Mehdi’s Notes

Article updated on

Read all about the changes.

I had multiple options for the title of this note, from being neutral to opinionated, or even pedantic. I deliberately kept the worst.

The rant has been written before having discovered this comment and its answers on the related GitHub community discussion. If you’ve already read what’s there, you won’t learn anything new here. (I am actually glad my observations were all backed by others before I even published them.)

GitHub Markdown syntax for alerts considered harmful ​

Vitepress 1.0.0-rc.40 adds support for the GitHub syntax for alerts and converts it into custom containers.

The issues ​

Thou I’ve been an early adopter of this syntax on GitHub, I’ve decided not use it in other contexts:

md
> [!NOTE]  
> Lorem mynote ipsum.

Here’s why:

  • The content of the heading first sentence is predefined: goodbye freedom of writing, or translations.
  • You have to use the syntax for a blockquote, but it gets replaced by a <div> containing the inner content. This impacts the portability of Markdown documents to other systems: they will create a blockquote, no matter your initial respect for semantic.
  • You have to remember limitations that raise questions. Lot of them.

In any system, the previous example would be a paragraph inside a <blockquote>:

html
<blockquote>
    <p>NOTE Lorem mynote ipsum</p>
</blockquote>

But this syntax turns them into two paragraphs inside a <div>.

In GitHub:

html
<div class="markdown-alert markdown-alert-note">
    <p class="markdown-alert-title"><svg>…</svg> Note</p>
    <p>Lorem mynote ipsum</p>
</div>

In Vitepress:

html
<div class="note custom-block github-alert">
    <p class="custom-block-title">NOTE</p>
    <p>Lorem mynote ipsum</p>
</div>

Use Vitepress custom containers instead ​

Vitepress custom containers are more suitable in any situation: you get the full power of the previous example, but with full semantic support and the ability to put whatever you want as first sentence:

md
::: info My first line
This is a paragraph.
:::

HTML output:

html
::: <!-- 👈 not shown in Vitepress -->
<div class="info custom-block">
    <p class="custom-block-title">My first line</p>
    <p>This is a paragraph.</p>
</div>
::: <!-- 👈 not shown in Vitepress -->

And if you are reading it on my blog, it looks like this:

My first sentence

This is a paragraph

The ::: will look disgracious on other systems, but I prefer this trade-off over incorrect semantic: looking at my blog, only 5 of 11 occurences (at the time of writing) would have been achievable with the GitHub syntax… and this is assuming I don’t need to customise the first sentence, which I always do, giving a 0 of 11 occurences.

Wrapping up ​

Instead of having to figure out if I can use the GitHub syntax at a given place, it’s better maintenance to not use it at all. The only use case I can think of for the GitHub syntax outside of GitHub is when you don’t care about semantic (e.g. paper books).

When the GitHub syntax was initially designed, I doubt the flexibility, the semantic or the compatibility with other systems were considered. Actually, the exact issues I’ve observed were raised immediatly after the initial post went online: exactly 9 hours for the first and 1 day and 58 min. for the second.

I think Vitepress shouldn’t encourage it, and could revert it (progress: it’s not reverted but you’ll soon be able to disable it if you want, see the updates). I also think GitHub should change its decision and adopt a custom syntax that doesn’t break semantic: a candidate for this is the one used by Vitepress for custom containers, which is also used by Docusaurus, and for which extensive discussions exist since a decade ago.

Hey, but if GitHub reverts it, that would looks bad on my documentation.

Well, yes, and mine too: and actually it already changed at least once since the early implementation. And worst: at work I have documentation that now needs to be ingested in another system that doesn’t give a tilde about this syntax. So I’m very fine with breaking it again, but hopefully for a better design.

Updates to this article ​

​

Yesterday I shared this article on the GitHub discussions of both GitHub and Vitepress:

I’ve updated the article to reflect these new informations. See code difference in the repository.