Adds admonition block-styled content to Obsidian.md, styled after Material for MkDocs
Obsidian 0.14 adds support for Callout boxes!
With this change, Admonitions will be transitioning to a plugin that enhances the core callout box feature.
What does this mean, you might ask?
- All of your existing code block admonitions will continue to work, and will always work!
- You can continue to use Admonitions to create custom types, and all of your custom types will just work as a callout, without you having to do anything!
- If you have any Microsoft Document syntax admonitions, they will have to be converted to the new callout box syntax - there is a button in Admonition settings to auto-convert these for you.
- You can use Admonitions to set default titles, default collapse states, or defaulting to not having a title.
- Admonitions adds helpful editor suggestors for quickly entering your custom callout boxes.
- Admonitions adds helpful commands for inserting callout boxes, including the ability to register commands for specific types.
Place a code block with the admonition type:
```ad-note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla.
```Becomes:
```ad-<type> # Admonition type. See below for a list of available types.
title: # Admonition title.
collapse: # Create a collapsible admonition.
icon: # Override the icon.
color: # Override the color.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla.
```Please note that as of 4.4.1, the title, collapse, icon and color parameters must be at the top of the block, in any order.
The admonition will render with the type of admonition by default. If you wish to customize the title, you can do so this way:
```ad-note
title: Title
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla.
```
Custom titles are rendered as Markdown, so they support the full Obsidian Markdown syntax.
Leave the title field blank to only display the admonition.
```ad-note
title:
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla.
```
Use the collapse parameter to create a collapsible admonition.
collapse: open will start the admonition opened on render, but allow collapse on click.
If a blank title is provided, the collapse parameter will not do anything.
Admonitions may be set to be collapsible by default in settings.
The admonition icon can be overridden using the icon parameter. The icon name entered must be the exact icon name from FontAwesome or RPGAwesome.
```ad-note
icon: triforce
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla.
```
The admonition color can be overridden using the color parameter. The color entered must be an RGB triad.
```ad-note
color: 200, 200, 200
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla.
```
An admonition with no content will render as just the title block.
```ad-note
```
Nesting admonitions may be done by increasing the number of backticks.
Example:
`````ad-note
title: Nested Admonitions
collapse: open
Hello!
````ad-note
title: This admonition is nested.
This is a nested admonition!
```ad-warning
title: This admonition is closed.
collapse: close
```
````
This is in the original admonition.
`````
Code blocks may be nested inside admonitions using a method similar to Nesting Admonitions above.
Additionally, for a single layer, the ~~~ markdown codeblock syntax may be used:
````ad-info
```ad-bug
title: I'm Nested!
~~~javascript
throw new Error("Oops, I'm a bug.");
~~~
```
```javascript
console.log("Hello!");
```
````
The following admonition types are currently supported:
| Type | Aliases |
|---|---|
| note | note, seealso |
| abstract | abstract, summary, tldr |
| info | info, todo |
| tip | tip, hint, important |
| success | success, check, done |
| question | question, help, faq |
| warning | warning, caution, attention |
| failure | failure, fail, missing |
| danger | danger, error |
| bug | bug |
| example | example |
| quote | quote, cite |
See this for a reference of what these admonitions look like.
The default admonitions are customizable by creating a user-defined admonition of the same name.
Custom admonitions may be created in settings. Creating a custom admonition will also enable it to be used as an Obsidian callout.
Creating a new admonition requires three things: the type, the icon to use, and the color of the admonition.
Only one admonition of each type may exist at any given time; if another admonition of the same type is created, it will override the previously created one.
If a default admonition is overridden, it can be restored by deleting the user-defined admonition.
Please note that by default, the background color of the title is simply the color of the admonition at 10% opacity. CSS must be used to update this.
Images can be uploaded to use as an admonition icon instead of an icon from a downloaded icon set.
These images will be resized to 24px x 24px to be stored in the plugin's saved data.
To remove an image icon, simply choose an icon in the icon chooser text box.
Several commands are available for the plugin by default.
If these two commands are triggered with an open note, all collapsible admonitions will be collapsed or open respectively.
This will open a modal where the admonition type, title and collapse behavior can be set, then the generated admonition code block will be inserted into the open editor.
Commands may be registered for each custom admonition type to insert them into an open note by clicking the Register Commands button in Settings.
3 commands will be registered: Insert <type> Callout, Insert <type>, and Insert <type> with Title.
The selected type will be inserted as an Obsidian callout, and any selected text will be included with it.
The selected type will be inserted as a codeblock admonition, and any selected text will be included with it.
The selected type will be inserted as a codeblock admonition, and any selected text will be included with it. The title: parameter will also be added and the cursor will be placed at that line.
Mermaid graphs are supported by Admonitions, but with some caveats:
- You cannot combine mermaid graphs and embeds/transclusions.
- Mermaid graphs do not work in collapsed-by-default admonitions.
❗ This syntax has been officially removed as of Admonitions 7.0.0.
Use the Obsidian Callout box syntax instead!
As of version 6.0.0, there is a new setting: Enable Non-codeblock Admonitions.
This setting is highly experimental and may not work as expected, and there are a few caveats listed at the end of this section to keep in mind.
This setting allows for creating an admonition without wrapping it in a code block, which means that links and tags will sync into Obsidian's cache. A non-codeblock admonition may be created using the following syntax:
!!! ad-<type> Title goes here!
content
--- admonition
This will create the appropriate admonition type, embed the content, and give it the supplied title.
Titles should be placed after the admonition block. Currently, markdown in titles is not supported.
An empty title can be created by either placing two spaces after the admonition type:
!!! ad-<type>
content
--- admonition
or by placing empty double quotes:
!!! ad-<type> ""
content
--- admonition
A collapsible admonition may be created using the following syntax:
??? ad-<type> Title goes here!
content
--- admonition
A collapsible admonition may default to "open" by appending a +:
???+ ad-<type> Title goes here!
content
--- admonition
- Changes to the admonition after render require the cache to be cleared. The note must be closed and re-opened (and sometimes, a different note must be opened first).
- This is all changes, including the admonition type, title, content, even whether or not a collapsible admonition is open or closed initially.
- Nested admonitions are not currently supported.
If you experience any bugs using this setting, please create an issue and I will look into them.
❗ This syntax has been officially removed as of version 8.0.0.
Use the Obsidian Callout box syntax instead!
As of v6.8.0, an additional non-code block syntax can be used that is inspired by the Microsoft Document Syntax to render admonitions.
⚠️ Please note:Unlike the Microsoft Document Syntax, the type is not required to be upper case.
The plugin will use an exact-match first, then try to find a case-insensitive match.
> [!quote]
> This is an admonition!
This syntax can also be used on indented code blocks:
[!quote]
This is an admonition!A title can be added to the MSDoc-style admonition by appending it after the type.
> [!quote: This is the title!]
> This is an admonition!Like the code block syntax, providing an empty title will remove the title from the rendered admonition.
> [!quote:]
> This admonition won't have a title!Collapse can be set by appending the following characters after the brackets:
| Character | Collapse Type |
|---|---|
+ |
open |
- |
closed |
x |
none |
Obsidian plugins do not work on publish sites; however, version 6.4.0+ has an option to generate a JavaScript file that can be used on Publish sites with custom domains.
Obsidian Publish only allows external JavaScript on publish sites with custom domains. If your Publish is ran through Obsidian, this will not work.
Instructions:
- Go the Admonition settings tab and click the "Generate JS for Publish" button.
- Save the JavaScript file.
- Copy the contents of the JS file to your
publish.jsfile. - Add the contents of the
assets/main.cssfile to yourpublish.cssfile.
Please note that I can give no guarantees of stability on your publish site. Other JavaScript you include may conflict with this file. If you run into an issue using it, please create an issue on this repository and I will try to help you.
Additional icon packs can be downloaded in settings.
Want to add an existing icon pack? Make a pull request with the following:
- Add a new folder in the icons folder with the name of your icon set.
- Create an
icons.jsonfile that has the icons defined as an Object. Please see the Octicons json for reference. - Put your icon pack's information in the two variables in the Icon Packs file.
Custom admonition types can be created and managed in this section of the settings.
This button will generate a CSS snippet that you can save and use for your custom callout types.
Custom admonitions can be imported in settings from a JSON array of definitions.
At a minimum, you only need a valid admonition type:
[
{
"type": "my-custom-type"
}
]This will use the pencil-alt FontAwesome icon and a random color, and set all other properties as false.
However, you can specify an icon and color as well:
[
{
"type": "my-custom-type",
"icon": "globe",
"color": "120,120,120"
}
]If you want to specify an icon pack, you can do so like this:
[
{
"type": "my-custom-type",
"icon": {
"name": "globe",
"type": "font-awesome"
},
"color": "120,120,120"
}
]All of the possible fields are defined here.
Settings specific to admonitions are managed in this section.
A drop shadow will be added to admonitions by default.
If this setting is off, rendered admonitions will receive the .no-drop class.
All admonitions will be collapsible by default, unless collapse: none is set in the admonition parameters.
⚠️ This setting is only available when Collapsible By Default is true.
Set the default collapse type used when setting an admonition collapsible by default.
A "Copy Content" button will be added to the top-right corner of the admonition & callout content.
Turn this setting off to prevent admonition titles from being rendered as markdown.
Controls whether or not a rendered admonition will receive a color.
Turn this off to totally control color via CSS.
Admonitions with no content are hidden by default.
⚠️ Please note that this only works for Admonitions that have no text content whatsoever.
The plugin comes pre-bundled with the entire Font Awesome Free icon set. Turn this setting off to not include them in the icon picker.
Existing custom Admonitions that use Font Awesome icons will continue to work.
Additional icon packs can be downloaded to supplement the included Font Awesome Free icon set.
Downloading an icon pack requires an internet connection.
Current additional icon packs available are the Octicons set and the RPG Awesome set.
📝 For backwards compability, if an Admonition was created prior to version 7.0.0 using an RPG Awesome icon, the pack will try to be downloaded.
Obsidian 0.14 has introduced Callout boxes to its core functionality using a similar syntax to the Microsoft Document callouts.
This has rendered the Microsoft Document syntax for Admonitions obsolete, but Admonitions can still be used to create and manage your custom callout types.
Your existing code block Admonitions will always work!
❗ This setting has been removed as of version 7.0.0.
It is recommended to use the Obsidian Callout box instead.
Enabled use of !!! ad-<type> style admonitions. No longer supported, will be removed in a future version.
❗ This syntax has been officially removed as of version 8.0.0.
Use the Obsidian Callout box syntax instead!
Enables use of the Microsoft Document Syntax for blockquote admonitions.
❗ This syntax has been officially removed as of version 8.0.0.
Use the Obsidian Callout box syntax instead!
Enables use of the Microsoft Document Syntax for indented code blocks.
❗ This syntax has been officially removed as of version 8.0.0.
Use the Obsidian Callout box syntax instead!
Enables use of the Microsoft Document Syntax in live preview.
This feature is still under development and you may experience rendering bugs.
This button can be used to convert any existing Microsoft Document syntax Admonitions to the new Callout box syntax.
Enable syntax highlighting when editing admonition code blocks.
The plugin will attempt to syncronize links to the metadata cache to be displayed in graph view.
This setting is experimental. Links will only be synced when rendered in an admonition and they will not persist if you close and re-open Obsidian.
Please see this issue for more information.
If you require links to be fully synced, it is recommended to use the Microsoft Document Syntax.
Use this setting to enable Admonitions on custom-domain Obsidian Publish websites.
See Publish for more information.
No additional features are planned at this time. If there is a feature missing that you would like to see, please open an issue.
- Add the ability to collapse the admonition
- Custom admonitions
- Settings tab to customize icon and color of all admonitions
- Ability to render markdown inside an admonition
From Obsidian v0.9.8, you can activate this plugin within Obsidian by doing the following:
- Open Settings > Third-party plugin
- Make sure Safe mode is off
- Click Browse community plugins
- Search for this plugin
- Click Install
- Once installed, close the community plugins window and activate the newly installed plugin
- Download the Latest Release from the Releases section of the GitHub Repository
- Extract the plugin folder from the zip to your vault's plugins folder:
<vault>/.obsidian/plugins/
Note: On some machines the.obsidianfolder may be hidden. On MacOS you should be able to pressCommand+Shift+Dotto show the folder in Finder. - Reload Obsidian
- If prompted about Safe Mode, you can disable safe mode and enable the plugin. Otherwise head to Settings, third-party plugins, make sure safe mode is off and enable the plugin from there.
You can follow the same procedure to update the plugin
This plugin comes with no guarantee of stability and bugs may delete data. Please ensure you have automated backups.
If you're using Obsidian to run/plan a TTRPG, you may find my other plugin useful:
- Obsidian Leaflet - Add interactive maps to Obsidian.md notes
- Dice Roller - Add some randomness to your notes
- Initiative Tracker - Track TTRPG Initiative in Obsidian
- 5e Statblocks - 5e-style statblocks inside notes!
