markdown-callouts
markdown-callouts copied to clipboard
oprypin
FEATURE REQUEST: "Microsoft Docs Alerts" style Callouts
You can fork the extension and just change the regular expression, should be relatively easy. Let me know if you run into trouble. This syntax doesn't match the goals of the extension, so will not be supported
Just as a note, as I redirected someone to this project as they were looking for GFM style callouts, it appears GitHub has pivoted to use "Microsoft Docs Alerts": https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts. This change is likely to align with existing syntaxes that are more recognizable to users.
Regardless, this project does not explicitly state it is attempting to support GitHub style callouts, and aims to only fallback to what is deemed a reasonable output for rendering if the syntax is not supported, but my impression was that is why the syntax was chosen. So, if this project aims to have callouts render in GitHub as callouts, GitHub has pivoted to a new style, this requested style, so supporting this approach may be desirable, if that goal aligns. If not, it may be helpful to explicitly state that in the docs as now there may be some confusion.
@facelessuser @llucax
The background on what "GitHub style" meant historically is here: https://github.com/oprypin/markdown-callouts/issues/16#issuecomment-1817494201 This extension was made before it became a thing but I've been following the topic with interest.
So I'd be interested in also supporting the "obsidian" style which is now the "GitHub" style. However this style would be very limited, as they don't define any ability to set a custom title of the admonition, or to set different CSS classes. The syntax is very simple and very "unforgiving" - nothing extra is allowed on the first line. So if the extra features are supported, it would no longer provide graceful degradation on GitHub, which is not aligned with this project's goals but I keep thinking about it in the background.
Base example (really the only thing that works on GitHub):
[!NOTE] Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
There is this project which simply moved forward and made some additional syntaxes. (Also started before GitHub admonitions were a thing) https://github.com/sondregronas/mkdocs-callouts
Which as you can see doesn't display as anything good on GitHub.
Custom title example (still Obsidian-compliant but not GitHub-compliant):
[!NOTE] Custom title Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Foldable block example (still Obsidian-compliant but not GitHub-compliant):
[!NOTE]- Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Custom class example (totally made up by that plugin):
[!NOTE inline end] Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
However I am not happy with just only sometimes having graceful degradation, or with how that project is implemented (it's a simplistic find&replace rather than a Markdown extension)
So, interested in making something but unsure how to proceed.
Actually if our goal is GitHub only, then we could start inventing yet another syntax, such as:
[!NOTE] Custom title. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
But can't think of anything remotely reasonable for custom classes or foldable blocks.
And @llucax would you really be happy with the pure GitHub admonition style considering it supports only the most basic type of admonition with 0 extra features? What would you do when you decide that you want a custom title? This is why I believe that this extension's current style may still be the most flexible solution.
Understood. My interest is mainly to understand the direction of this project for the sake of redirects. There are a lot of people who orbit around the GitHub "way", and they often like things to be consistent, even if that means limited. This may not be your project's goal, I'm just looking for clarification.
And @llucax would you really be happy with the pure GitHub admonition style considering it supports only the most basic type of admonition with 0 extra features?
Yes. For me it adds value. My main use case is having a README.md that can be seen nicely in GitHub but also can be included in mkdocs and also seen nicely there. My goal is not to be able to view all the mkdocs-specific markdown files nicely in GitHub.
What would you do when you decide that you want a custom title?
Suck it up and not have it. For my restricted use case, is not that important to have custom titles.
This is how the README of the project with more thought about documentation we have looks like:
https://github.com/frequenz-floss/frequenz-channels-python/
(I prefer removing the inline end if it brings nicer syntax to GitHub). Then the readme is included in the docs, see for example:
- https://github.com/frequenz-floss/frequenz-channels-python/blob/v1.x.x/docs/index.md?plain=1
- https://frequenz-floss.github.io/frequenz-channels-python/v1.0-dev/
Thanks!
https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types "CAUTION" can be represented as "DANGER" class. What could we represent "IMPORTANT" as? Actually probably best left in the default style
I went ahead and implemented GitHub-style syntax, matching its behavior as strictly as possible
- https://github.com/oprypin/markdown-callouts/pull/18
Try it out and let me know if you can find any mismatching edge cases :D
pip install -U markdown-callouts
and the other part of instructions is
markdown_extensions:
- github-callouts
ERROR - Config value 'markdown_extensions': Failed to load extension 'github-callouts'.
ModuleNotFoundError: No module named 'github-callouts'
:-/
squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types "CAUTION" can be represented as "DANGER" class. What could we represent "IMPORTANT" as? Actually probably best left in the default style
Right. Yeah. I guess that can be left to the user to properly customize, or have a separate feature request to add caution and important admonitions to mkdocs-material. I actually find myself several times wanting important, and was going to add a custom admonition for it anyways.
markdown_extensions: - github-callouts
Also silly question, any reason not to call the extension github-alerts instead, as this is the official GitHub name for them?
I merged and released this.
- https://github.com/oprypin/markdown-callouts/pull/18
The only documentation is release notes, didn't write anything else yet. https://github.com/oprypin/markdown-callouts/releases/tag/v0.4.0
pip install -U markdown-callouts
This is a godsend of a feature, and IMO it should be prominently advertised in the project README.
Glad to see the support for obsidian callouts
And @llucax would you really be happy with the pure GitHub admonition style considering it supports only the most basic type of admonition with 0 extra features? What would you do when you decide that you want a custom title? This is why I believe that this extension's current style may still be the most flexible solution.
About the custom title problem you mentioned before I found that obsidian callouts has carried out a solution like below
Can you add this feature to the project? This will really improve the experience of using Obsidian+mkdocs to publish my articles. @oprypin
