Docusaurus: Feature Request - Ability to add Notes block (Callouts) in docs

[CaptainT33mo]

🚀 Feature

Ability to add Warning, Info, Success and Danger Notes (Callouts) block in Docusaurus.

Motivation

The main source of motivation for this issue came from Readme because I've used this in my company. And readme has this Notes Block which they call Callouts which support Warning, Info, Success and Danger Callouts as shown in the attached image.
https://i.postimg.cc/1R2n4fPR/5-BDEE76-D-6-A24-46-C5-B3-F7-1-F9-E7-E0-BB72-A.jpg

Pitch

I think it would be great to notify the users about the change in the code versions by showing Success
or Warning Notes block. Or warn the user that something will be deprecated by showing them the Danger block.

The Notes block should primarily consist of an icon which will depict the type of Notes Block and its respective color. Also, it should have a heading and a description section.
In the .md file one can somrthing like this:

[notes]
    {
      "type": "info",
      "body": "Add Permissions outside the application Tag `<application>`"
    }
[/notes]

[amimas]

I'd love to see this feature. Just a quick comment on the examples used above. Typically you'd use Markdown's built-in code block for that type of contents. For example:

````markdown

    {
      "type": "info",
      "body": "Add Permissions outside the application Tag `<application>`"
    }

````
For tips or warning about certain info, it'd be great to be able to have different coloured content blocks.

[leonardfactory]

I'm thinking about this too (docusaurus is awesome, except for missing asciidoc 😄!). I'm looking into Remarkable plugins as a way to add callouts, but I need to dig deeper.

[leonardfactory]

Hi @CaptainT33mo @amimas , I've actually developed this plugin for remarkable, remarkable-admonitions which adds admonitions (callouts) support to Remarkable and hence Docusaurus

I've added some docs in the README to use it and a default CSS to match docusaurus style. Let me know what do you think, I'm starting to use it in my projects but some feedback is always helpful 👍

[amimas]

It looks really nice. I'm going to try it out. Hopefully it can be integrated into Docusaurus so that it's available out of the box without needing custom configuration.

[CaptainT33mo]

It looks great @leonardfactory . I was actually working on the same but I didn't get the time to finish it and you've done a great job here.
I think this should be added in docusaurus 1.7.3 by default. 👍 💯

[JoelMarcey]

cc @yangshun @endiliey

[endiliey]

I personally feel that markdown features are best left as markdown parser plugins for scalability purpose.

Keeping everything on docusaurus can make it hard to maintain. Furthermore, we moved to MDX as our default markdown parser on v2 (cos we want more React on Markdown).

However, we'll be accepting PR on the docs if someone want to mention how to add callouts with https://github.com/favoloso/remarkable-admonitions

The documentation here is also very good
https://github.com/favoloso/remarkable-admonitions#with-docusaurus

[elviswolcott]

Adding here because it is what came up when I searched for "admonitions" + "docusaurus 2".

I just upgraded a project to v2 and realized that meant no `remarkable-admonitions.

I wrote a remark plugin that does the same thing as remarkable-admonitions, but for remark called remark-admonitions. It has styles that work with Infima as well.

It should be up on NPM as of a few minutes ago.

https://github.com/elviswolcott/remark-admonitions

[yangshun]

Thanks @elviswolcott! We will want to incorporate it into theme-classic as part of the core offering. Would you have time to look into it? Otherwise we will add this to our backlog.

[elviswolcott]

I'll try to get a PR together when I have some time later today/tomorrow.

I might be rewriting a bit of the plugin first because it's currently doing some overly complex stuff to parse SVG strings into MDAST so that everything can happen in a tokenizer when it should really be a tokenizer + a handler.

[elviswolcott]

@yangshun I've been poking around theme-classic a bit and I'm not quite sure where my package would fit in.

It looks like mdx/webpack setup should be handled by a plugin and styles by a theme. Is this the right path forwards?

[yangshun]

You're right. I think we just need to add your plugin to preset-classic, not the theme.

[elviswolcott]

I've got the plugin added through preset-classic but am not quite sure the best way to go about adding the styles.

[elviswolcott]

Figured it out. Turns out requireing from scoped package in client-modules.js doesn't work (not completely sure why). I'll publish a new version of the package with the styles and open a PR with the necessary docusaurus changes tomorrow after some testing.

[elviswolcott]

2224 is up to add admonitions!

[lex111]

Resolved in ##2224