GitHub-like alerts using the rehype-github-alerts plugin
We are about to use the rehype-github-alerts plugin to render alerts (admonitions/callouts) in a similar way to how GitHub does it. rehype-github-alerts is a plugin I did a while back after I first saw the GitHub alerts RFC in which GitHub suggests adding a new alerts syntax to their GitHub markdown
The rehype github alerts plugin is not a copy of the exact GitHub source code as the code used for their implementation is NOT open source, but the rehype github alerts attempts to mimic the GitHub alerts appearance and features, meaning that when you add alerts into your markdown and publish it on GitHub then the rendered alert output should be very similar to what you get when using this plugin, of course, the alerts style might be different for your project depending on what CSS you apply to the alerts
This plugin attempts to mimic the GitHub alerts by implementing the same features, it is however possible to configure some of the features, for example, add new custom types of alerts (the default GitHub alert types are Note, Tip, Important, Warning, and Caution). You can also customize the CSS, to change how the alerts get displayed (check out the rehype github alerts README for some documentation and more examples), as you probably noticed I use the plugin a lot on this website and my alerts look pretty different from what they look like on GitHub
rehype-github-alerts installation
To add the rehype github alerts plugin, we first need to install the package:
Next, we need to edit our Next.js configuration file to add the plugin to our MDX setup:
Line 10: we import the rehype-github-alerts plugin
Line 57: we add the rehypeGithubAlerts plugin to our rehype plugins configuration array
Rehype github alerts in action
The plugin is now ready to be used, so we can now add some examples to our playground:
Note
If you get the following linting error for what is between the square brackets ([]):
Unexpected reference to undefined definition, expected corresponding definition (!warning) for a link or escaped opening bracket (\[) for regular text eslint(remark-lint-no-undefined-references)
If you now launch the dev server and then open the playground URL http://localhost:3000/gfm_playground in your browser, you will see that alerts get rendered
The alerts should be visible, they are not well aligned and all have the same color, which is why in the next chapter we will add some CSS to improve that
Styling rehype github alerts
Now, to mimic the style alerts we have on GitHub, we will add some custom CSS to our global.css CSS file:
Have another look at http://localhost:3000/gfm_playground, to have a look at the updated alerts style
The alerts should now use similar colors than those used by github (github has different colors for light and dark schemes, so I took those for light text on a darker background, but feel free to change the colors to whatever works well for your project)
Congratulations 🎉 you have now added support for markdown alerts that are compatible with GitHub (flavored markdown)
If you liked this post, please consider making a donation ❤️ as it will help me create more content and keep it free for everyone