Support Admonition

[rioka]

Please Select if your Request is Either something new or an Enhancement

• [ ] Enhancement of an existing Feature.
• [x] Request of a new feature.

Please select the area your request applys to. (Multiple selections are Possible)

• [ ] Onboard. Initial vault setup and import/export pods
• [ ] Create. Note creation, lookup, snippets and templates
• [ ] Retrieve. Backlinks, references, graph view
• [ ] Structure. Refactoring, multi-vault and schemas
• [ ] Publish. Sharing your repo with the world
• [x] Misc (Choose this if your not sure)

Describe the solution you'd like

Add support for admonitions

Describe alternatives you've considered

Using blockquote

Additional context

Ideally

Workaround

[jonathanyeung]

Thanks for the suggestion @rioka. Is this !!! notation the kind that you're expecting? https://squidfunk.github.io/mkdocs-material/reference/admonitions/

[paulbrianstephenson]

Hi there, I'd really love to see this kind of feature too. Another example of how this may look is:

(https://getbootstrap.com/docs/5.1/components/alerts/)

Could this be achieved using CSS, Nunjucks, SASS, or something similar? Apologies, I've done some Googling, but this really isn't my area of expertise.

[hikchoi]

I've seen these sort of callout features implemented with standard markdown blockquotes so that when the user starts a blockquote with a specified keyword, the entire blockquote gets rendered into a custom styled callout.

e.g.

> Info
>
> This will be styled into a callout

would generate the HTML

<blockquote class="callout info">
  <p class="callout_title">INFO</p>
  <p class="callout_body>This will be styled into a callout</p>
</blockquote>

and we can provide some basic stylings to the callout CSS class and let the users customize them like so

.callout .info {
  ...
  --background: #123456;
  ...
}

Would an approach like this be better? My reasoning is that if we can enable a way to automatically give a CSS class to a blockquote that starts with a set of predefined (and user definable) keywords, it would be much simpler to implement than trying to introduce another custom syntax to the mix.

It would also be easier to export it to other places since it will just be a standard blockquote outside the context of previewing.

A quick search for existing remark plugins for admonitions also tells me that most of them are tailored towards using them in specific documenting services and we would most likely have to implement out own remark plugin to support it in Dendron anyways.

[rioka]

Thanks for the suggestion @rioka. Is this !!! notation the kind that you're expecting? https://squidfunk.github.io/mkdocs-material/reference/admonitions/

Yes

[rioka]

I've seen these sort of callout features implemented with standard markdown blockquotes so that when the user starts a blockquote with a specified keyword, the entire blockquote gets rendered into a custom styled callout. ...

That would be fine too...

In this case, would markdown syntax (ie monospace, bold, list, ...) inside the generated HTML be preserved?

[hikchoi]

In this case, would markdown syntax (ie monospace, bold, list, ...) inside the generated HTML be preserved?

If we do go the route of implementing this feature ourselves, we will have full control over how the callout will be transformed into HTML. So the answer is yes.

[ScriptAutomate]

Another example of admonition implementation in a static site, becoming text boxes with colored labels (generated by Sphinx with furo theme):

• https://pradyunsg.me/furo/reference/admonitions/

At the top-right of page, can flip the theme between dark/light modes. This page and these admonitions are done in a format that looks just like the rendered ideal example mentioned by @rioka

MyST-parsed markdown approaches custom admonitions like this with code blocks labels, instead of blockquotes, with special keywords encased in {} which looks like:

</code>
</br>
</br>

Not sure what's an easier approach, though. Different avenues that come to mind, based on my experience with other tools:
- Blockquotes with a custom header label, that will format it as an admonition? This approach is nice in that it's minimal work for the Markdown editor, since it would be seen as generic Markdown. Changes would just need to be made for both preview and publishing.
- `!!! note` [like MKDocs](https://squidfunk.github.io/mkdocs-material/reference/admonitions/)?
- Codeblocks with a custom parser instead of code-language syntax highlighting, similar to MyST's approach?
- It looks like Hugo supports a special Attribute list [to things like blockquotes](https://gohugo.io/news/0.81.0-relnotes/#attribute-lists-after-markdown-blocks)
- For Hugo, it looks like people most commonly use [shortcodes](https://gohugo.io/content-management/shortcodes/), and have admonitions configured for use such as where you see `{{% note %}}` in this doc: https://github.com/gohugoio/hugoDocs/blob/master/content/en/getting-started/quick-start.md
  - Example rendering in the Tip box: https://gohugo.io/getting-started/quick-start/#step-6-customize-the-theme
  - This approach may clash with Nunjucks experimental support though, unless Nunjucks could somehow be used as part of addressing admonitions? [Nunjucks with Dendron](https://wiki.dendron.so/notes/ba97866b-889f-4ac6-86e7-bb2d97f6e376.html#nunjuck-templates)
- A different approach?

[ScriptAutomate]

This came up in discussions around the Getting Started tutorial because we need to use quote blocks with an emoji as a workaround at the moment: https://github.com/dendronhq/dendron/discussions/1756#discussioncomment-1880880

Ex.

:bulb: TIP: Here is a tip!

[Xanaxus]

Hey, I found this Remark-Admonitions, while trying to get to work, hope this will help in the process of building it.

There is also a markdown-extend extension on the VS Code which should do the work, but I haven't been able to get it to work, while using Dendron. This works In the default viewer, though.

[ScriptAutomate]

Just to add to the docs convo, too, Microsoft has extended Markdown with their own admonition setup, too, which is part of their docs-markdown extension:

> [!NOTE]
> Information the user should notice even if skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Essential information required for user success.

> [!CAUTION]
> Negative potential consequences of an action.

> [!WARNING]
> Dangerous certain consequences of an action.

[andrey-jef]

fyi, Obsidian officially support callout blocks in their yesterday release[^1].

They adopt the Microsoft Docs style.

Supported types of callout blocks [^2]:

• note
• abstract, summary, tldr
• info, todo
• tip, hint, important
• success, check, done
• question, help, faq
• warning, caution, attention
• failure, fail, missing
• danger, error
• bug
• example
• quote, cite

[^1]: release note v0.14 [^2]: Obsidian Help

[kevins8]

ah, good to know. thanks for the notice!

On Tue, Mar 15, 2022 at 3:57 PM andrey-jef @.***> wrote:

fyi, Obsidian officially support callout blocks in their yesterday release 1 <#m_5594306185611178406_user-content-fn-1-88ddc003953830b9b45e01ae47eda84c> .

They adopt the Microsoft Docs style https://docs.microsoft.com/en-us/contribute/markdown-reference.

Supported types of callout blocks 2 <#m_5594306185611178406_user-content-fn-2-88ddc003953830b9b45e01ae47eda84c> :

• note
• abstract, summary, tldr
• info, todo
• tip, hint, important
• success, check, done
• question, help, faq
• warning, caution, attention
• failure, fail, missing
• danger, error
• bug
• example
• quote, cite

Footnotes

1.

release note v0.14 https://forum.obsidian.md/t/obsidian-release-v0-14-0-insider-build/33986 ↩ <#m_5594306185611178406_user-content-fnref-1-88ddc003953830b9b45e01ae47eda84c> 2.

Obsidian Help https://help.obsidian.md/How+to/Use+callouts ↩ <#m_5594306185611178406_user-content-fnref-2-88ddc003953830b9b45e01ae47eda84c>

— Reply to this email directly, view it on GitHub https://github.com/dendronhq/dendron/issues/1287#issuecomment-1068543621, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABPIPSKBIH726BQVGN73WDVAEIVVANCNFSM5DNOCZCQ . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

You are receiving this because you are subscribed to this thread.Message ID: @.***>

[ScriptAutomate]

As another update to add to the conversation, GitHub now supports their own form of admonitions (for just Warning and Note), at least in beta. The implementation may still change:

• https://github.com/community/community/discussions/16925

Note

> **Note**
> This is a note

Note This is a note

Warning

> **Warning**
> This is a warning

Warning This is a warning

[ccamara]

As someone who loves writing documentation, I would definitely see this implemented.

I do not know if it's of any use (apologies if it's not), but other tools such as quarto or docusaurus use an approach to admonitions/callouts that is similar for both and different as compared to the previous ones: both use :::

Docusaurus has the following syntax:

:::note

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::tip

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::info

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::caution

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::danger

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

which results in this

Source: https://docusaurus.io/docs/markdown-features/admonitions

Quarto uses a similar approach:

:::{.callout-note}
Note that there are five types of callouts, including:
`note`, `warning`, `important`, `tip`, and `caution`.
:::

:::{.callout-tip}
## Tip With Caption

This is an example of a callout with a caption.
:::

:::{.callout-caution collapse="true"}
## Expand To Learn About Collapse

This is an example of a 'folded' caution callout that can be expanded by the user. You can use `collapse="true"` to collapse it by default or `collapse="false"` to make a collapsible callout that is expanded by default.
:::

which results in this:

Source: https://quarto.org/docs/authoring/callouts.html