rehype-github-alerts: rehype plugin to mimick github alerts

[chrisweb]

Since github announced a new alerts feature in the community discussions, I have followed the thread and wanted to have a similar feature for my dev blog project

I first searched for plugin and found similar packages, for example:

• docusaurus admonitions that uses the generic directives syntax
• remark-github-beta-blockquote-admonitions that uses the same syntax as github but it is a remark and not a rehype plugin
• remark-hint another remark plugin, which uses a different syntax but the end goal is similar
• remark-macro yet another remark plugin, it too does not use the github syntax but the goal is again similar

... so if you want a remark plugin to do the job you have plenty to chose from, but I did not find one for rehype

Why a rehype plugin? Well in my search I had found this remark ticket in which @wooorm suggested that it would be best to implement such a feature in rehype, this is why I chose to do a rehype and not a remark plugin

I then decided to start working on it and today I finally released the first version of my plugin, it is called rehype-github-alerts and is now available on npm

If you use this plugin, you can add alerts into your markdown (same syntax as on github) like so:

> [!NOTE]  
> I'm a note :wave:

> [!IMPORTANT]  
> I'm important

> [!WARNING]  
> I'm a warning

And then remark will turn the markdown into html and finally the plugin will transform the html blockquotes into alerts, that hopefully look like this:

Note

I'm a note 👋

Important

I'm important

Warning

I'm a warning

I posted about the plugin here as I hope it will be useful to more devs then just me and hope the plugin will not break the web, feedback, bug reports and contributions are of course welcome 😃

[remcohaszing]

Although I disagree with the implementation GitHub chose, I definitely think it makes sense to support this in rehype-github. But is it considered stable yet or is it still an experimental feature?

An interesting note is that the [ may be escaped. This means it’s a transform based on the parsed markdown text content. It’s not a syntax extension.

Also no line break (trailing spaces in your example) is needed.

> \[!NOTE]
> I'm a note :wave:

Note

I'm a note 👋

[chrisweb]

Although I disagree with the implementation GitHub chose

I honestly also have my doubts, even more so after writing this plugin, but I also went through all the suggestions the community posted in the rfc discussion and I must say I have no clear preference for doing it one way or another, maybe time will tell and one of the many ways of doing it will emerge as a winner due to the fact that is has become the most used

I definitely think it makes sense to support this in rehype-github

those plugins were a big inspiration for me, I'm open for suggestions about how to proceed, like do you want to create a new project in the rehype-github monorepo? Or do you want me to move this project over to rehype-github (however my project has no readme that matches the ones I see in remark/rehype repos, it has not tests (yet), it is written in typescript, I don't use the same code style (but this wouldn't be a huge task to change it)? Or something else?

But is it considered stable yet or is it still an experimental feature?

It depends on how one would define "stable"... there has been a first major release back when the rfc got published (in may 2022) that used the **Note** style, today this is considered "legacy" and the new style is [!NOTE], there have been some iterations since the first announcement, the last one wasn't that long ago in october 2023, personally I think it is stable due to the fact that I don't think they will change the markdown syntax but maybe they will fine tune the html output, for example in october they improved support for nested blockquotes, I also added blockquote support to the rehype plugin. I however did not see an official message yet that confirms that this feature is considered stable by the github team. The discussion around the implementation is still very active, just last week someone posted a good comment about https://github.com/orgs/community/discussions/16925#discussioncomment-7461387 some use cases which don't work properly

It’s not a syntax extension.

yes, that aligns with what wooorm said in the remark ticket

Also no line break (trailing spaces in your example) is needed.

hmmm I'm not sure what you mean? I don't try to support soft to hard line breaks like github does in some places as I think this is remark-breaks job, what I do if there are no 2 trailing spaces at the end of the first line in the blockquote is that I extract the "type" ([!ALERT_TYPE]) from the text, then I delete the type from text and if something is left I add it as text to the alert "body" content (I'm not sure this is the best way to do it, though, but I think it gives the same result as what can be observed on github)

I'm currently testing the rehype github alerts plugin in a project and I think it works well for a first version, I have no tests yet and I'm not sure when I will have time to write some, I however have some ideas about how to improve the documentation a bit and will do that today

[chrisweb]

I added some clarifications to the project readme, for example how to customize the build option, what to do regarding soft line breaks github uses in some places and how to use the types both in typescript and javascript

[chrisweb]

Github released an update two weaks ago [Markdown] An option to highlight a "Note" and "Warning" using blockquote (Beta) Update - 14 November 2023 with two new alert tip and caution so I updated the rehype github alerts package and added those two today

[ChristianMurphy]

I posted about the plugin here as I hope it will be useful to more devs then just me

Thanks For sharing @chrisweb!

feedback, bug reports and contributions are of course welcome 😃

Looks pretty good some ideas and commentary

1. You may want to unlock dependency versions to ensure updates and fixes flow, consider using a minor version range (prefixed with ^) https://github.com/chrisweb/rehype-github-alerts/blob/daf61429c45c8b85be75a4a32512041758b85d5a/package.json#L37-L39
2. Generally avoid committing build artifacts, it adds noise, and some new contributors will modify the artifact instead of the source https://github.com/chrisweb/rehype-github-alerts/tree/main/dist
3. Avoid bundling and minifying published code, let downstream adopters build the code to their own needs, and receive dependency updates https://github.com/chrisweb/rehype-github-alerts/blob/daf61429c45c8b85be75a4a32512041758b85d5a/package.json#L7
4. Consider writing code in JavaScript (with TypeScript's JSDoc mode), you get all of the type safety without needing a compile step for the code to be usable https://github.com/chrisweb/rehype-github-alerts/blob/main/src/index.ts
5. Avoid I prefixed interfaces, they make code harder to read with no benefit (https://passionfordev.com/you-dont-need-to-prefix-interfaces-in-typescript-with-i/ and https://medium.com/@jonyeezs/hey-typescript-wheres-my-i-prefixed-interface-cd70efa10bd1) https://github.com/chrisweb/rehype-github-alert/blob/daf61429c45c8b85be75a4a32512041758b85d5a/src/index.ts#L6
6. Consider using prettier or dprint for code style consistency https://prettier.io/ or https://dprint.dev/
7. Tests help ensure code works as expected, node:test is stable and fast https://nodejs.org/api/test.html
8. When embedding source from another project, include a notice file with a copy of their license (https://infra.apache.org/licensing-howto.html) to ensure the terms of CC-BY-4.0 are met https://github.com/chrisweb/rehype-github-alerts/blob/c71edcea2cb9210946a315d96ab13ddfde8ac04b/src/index.ts#L26
9. Consider leveraging GitHub actions to automatically lint/test changes as they are committed/PRed https://docs.github.com/en/actions

[chrisweb]

Oh wow thank you, lots of good suggestions, I will go through them one by one tomorrow soon

[chrisweb]

I did some changes to the project:

1: I unlocked the dependency versions
3: ok makes sense, I added new build command for default build, removed the bundling and minfication
8: I already had a note in the README, but now I also added a NOTICE file in the root, hope this is the correct way to do it

the other points, they are all good comments, but for some I just don't have the time right now, for others they are a personal preference (which doesn't mean I would be against changing in the future to align the project with others)

all the other comments are good ideas, but I can't invest time in those at the moment

[chrisweb]

Today I released a new version that now includes a test suite, the coverage so far is 90+%

[chrisweb]

I released rehype-github-alerts v2, it fixes a bug, includes a test suite and add support for the two new alerts tip and caution