Admonitions for GhDocs

godylockz · January 6, 2024, 7:47pm

Use case or problem

Any chance obsidian can follow the Markdown syntax for admonitions (callouts)?

I tried to edit markdown for a ghdocs project and it didn’t end up working out using Obsidian. Would love the support.

For more details, I found a good issue on why it isn’t working right now - using a community plugin called “admonitions” they use codeblocks to do admonitions (callouts) and that isn’t going to work with mkdocs.

github.com/javalent/admonitions

Trying to understand why Markdown standard for admonitions is not being followed

opened 10:42AM - 03 Oct 21 UTC

closed 09:02PM - 03 Oct 21 UTC

justasojourner

Hi Jeremy — @valentine195 Firstly thank you and kudos for making the Obsidian… Admonition plug-in. I installed it and had a look around. I read in your notes for [release 2.0.0](https://github.com/valentine195/obsidian-admonition/releases/tag/2.0.0) that you stated: > Admonitions must be prefixed by "ad-" now to prevent collisions with other plugins. also, not stated in the version 2.0.0 release notes, but I have seen, admonitions have to be blocked as follows: ``` ``` ad-note Admonition message ``` ``` instead of ``` !!! note Admonition message ``` Obviously the admonitions '[standard](https://python-markdown.github.io/extensions/admonition/)', inasmuch as Markdown has a 'standard' for admonitions, is the latter form. Material for MkDocs [also states](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) it follows that standard. Unfortunately with respect to 'standards' in Markdown the following quote is all too true 😉 > The nice thing about standards is that you have so many to choose from. <cite>Computer Networks, 2nd ed.</cite> — Andrew S. Tanenbaum Anyway, gripes about Markdown aside, I was wondering why it is necessary for the Obsidian Admonition plug-in (Obsidian?) to change the syntax for admonitions: 1. The block code from `!!!` to ` ``` ` 2. Using 'ad-type' e.g. `ad-note` instead of `note`. I've looked at the TypeScript code but am not conversant in TypeScript and/or Obsidian plug-in code to follow fully. * Can you help explain the rationale/reason. Does the Obsidian core code not understand, is not able to deal with, `!!!` * Is it possible/impossible to use the standard format. You say it clashes with other plug-ins, does that include every single Obsidian plug-in? For example if your plug-in was forked and changed to use `!!! type` (that is assuming Obsidian itself can support) what plug-ins would be affected = **_All_** community plug-ins? / **_Some_** community plug-ins? / the Obsidian written plug-ins? **_The reason I ask_** is because I am wanting to use your plug-in for a MkDocs generated documentation website. I can (have) themed Obsidian to look almost exactly like the production website, but Obsidian lacks direct support for Admonitions. If we write admonitions the way your plug-in wants obviously they will look fine in Obsidian — but will not render on the production website — as MkDocs and Material for MkDocs are following the standard. Which sort of defeats the purpose of the exercise. Thanks in advance for any help/guidance for this.

joethei · June 30, 2024, 7:24pm

There are multiple competing standards for admontions / callouts.
There is no definitive Markdown standard for it, the markdown standard is also missing tables for example.
The very popular CommonMark spec has no mention of callouts / admonitions.

The standard we use is also being used by GitHub:

RedBearAK · July 4, 2024, 4:57am

@joethei

I just did a test of all the GitHub admonitions in Obsidian and then came to the forum to look for threads about GitHub admonition syntax support and found your comment from just a few days ago.

In my test I noticed that Obsidian seems to support using any random word inside the brackets, and such things will get the “NOTE” pencil icon and blue color. But only three of the current five supported GitHub admonitions get their own color and symbol/icon. It looks like “IMPORTANT” and “WARNING” are supported by Obsidian, but the newer (2023) admonitions of “CAUTION” and “TIP” just get the symbol and color of “WARNING” and “IMPORTANT”, respectively.

Do you know if there are plans to support the newer GitHub admonitions with their own colors and symbols? That would sure be nice.

“TIP” is green with a light bulb symbol on GitHub now, and “CAUTION” is red with an octagonal symbol like a stop sign, with an exclamation point inside.

Should I submit a feature request to have the support for GitHub admonitions updated to support all five, and maybe match the colors and symbols better?

I know there’s a community plugin that uses a different method for admonitions/callouts, but I like the GitHub admonitions since I already use them on GitHub Wiki articles and READMEs.

How they look in a GitHub gist:

How they look in Obsidian 1.6.5 Flatpak on Fedora 40: