Custom Note/Warning admonitions are not displayed correctly on GFM based GitHub Pages

[rickstaa]

Select Topic Area

Bug

Body

I am currently using the Note and Warning admonitions in the readme of one of my projects. In this project, I want to use the default GitHub pages Jekyll setup to create a simple webpage based on this. All elements except the custom Note/Warning admonitions seem to work. Since these warnings are relatively new, they are, I think, still not supported in the GFM GitHub page conversion. However, I could not find any documentation supporting this hypothesis 🤔.

How to reproduce

1. Create a readme file that contains the Note/Warning admonitions.
2. Set up GitHub pages according to GitHub pages documentation.
3. Use markdown: GFM in your Jekyll _config.yml file.
4. Build the documentation.
5. See that the admonitions are not displayed correctly.

[ettaboyle]

Welcome to the GitHub Community, @rickstaa, we're happy you're here! You are more likely to get a useful response if you are posting your question(s) in the applicable category and are explicit about what your project entails--giving a few more details might help someone give you a nudge in the right direction. I've gone ahead and moved it from general to pages for you. Good luck!

[rickstaa]

@ettaboyle. Great thanks! I wasn't aware the was a pages category 👍🏻.

[MarioPoneder]

@rickstaa
I am having the same problem. Were you already able to find a solution for it?

[rickstaa]

Hello @MarioPoneder, regrettably, the pursuit of a solution continues, and my webpage warnings persist in their slumber (see https://adsb.cool/). It appears that resolution rests in the hands of GitHub, as the required functionality has not yet found its place in the GFM parser.

[MarioPoneder]

Thank you for your response.
It unfortunately seems that GitHub Pages doesn't support GFM as of now, despite the "markdown: GFM" setting.

[rickstaa]

Thank you for your response. It unfortunately seems that GitHub Pages doesn't support GFM as of now, despite the "markdown: GFM" setting.

GFM should be supported by github pages (see https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/setting-a-markdown-processor-for-your-github-pages-site-using-jekyll). I think maybe the admonition creation logic has not bee implemented in GFM 🤔.

[MarioPoneder]

It should be supported, but I also found that checkmark lists "- [x] ..." and correctly switching between dark/light-mode images isn't supported either.

[daerlnaxe]

Hi, same problem here, about admonitions.

for checkmark it seems to be ok for me.

[Helveg]

Hi! I've went ahead and created a Jekyll plugin that renders GitHub flavored admonitions! Try it out here: https://github.com/Helveg/jekyll-gfm-admonitions

Building GitHub Pages with custom plugins can be quite involved, but I included detailed step-by-step instructions. It would be incredibly useful if you could let me know of any hiccups you encounter along the way.

[tlourey]

This worked for me once I created a new custom github action but I think there is a bug somewhere as there seems to be an extra < in front of the <style> tag that brings in the css

<<style> is what it adds that seems to present an extra < on the page

[tlourey]

Yes. I would like it if an admonition (aka alert) title could be supported. e.g. this doesn't work

> [!NOTE] my note has a title
> And here is my note

[!NOTE] my note has a title
And here is my note

but this does

Note

this is my note with no title.

Microsoft's learn mark up supports it, as does the VSCode built in markdown viewer.
Github doesn't seem to support it, & of course github pages doesn't support them at all and this plugin is the only thing that gets you close.

It was discussed in https://github.com/orgs/community/discussions/16925 and but never made it through. To be fair I don't think (or can't find) it as part of:

• Current Common Markdown Spec
• The original spec
• the GFM Spec (Older CommonMark version + Github Extensions

but it does seem often desired and implemented, just not everywhere.

That and the script bug I mentioned.

The documentation did take me a couple of goes but I think that may have been me getting my Jekyll knowledge up to speed at the same time.

[Helveg]

Hi! Thanks for the traction on my post. I opened Helveg/jekyll-gfm-admonitions#5 to support your feature request.

The documentation did take me a couple of goes but I think that may have been me getting my Jekyll knowledge up to speed at the same time.

Honestly, same for me when I started investigating how to get this done with a custom GitHub Pages build! I think 99% of users of the plugin will have never customized Jekyll before, or ever used Ruby. So any feedback you had on which parts were still confusing would be appreciated, I can surely include a couple of detailed asides that help first time users and that advanced users can just scroll past

[profesorasix]

Hi!
Trying to get admonitions in my github page. Maybe confused but "jekyll-gfm-admonitions" is not in the github-pages whitelist. Has it to be included as thrid party plugin?

[Helveg]

No indeed, you have to create a custom build as outlined by the Jekyll docs