Adds admonition block-styled content to Obsidian.md, styled after Material for MkDocs
Please note, as of 2.0.0, all admonitions must be prefixed with ad-
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.
`````
Admonitions may also be nested inside each other using the Python Markdown syntax.
⚠️ Please note that this syntax cannot be used for the original admonition. It must be a codeblock (```).
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 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 Font Awesome or RPG Awesome.
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.
This is all of the CSS applied to the admonitions. Override these classes to customize the look.
The full CSS is located in main.css.
Every admonition receives the following CSS classes:
:root {
--admonition-details-icon: url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M8.59 16.58L13.17 12 8.59 7.41 10 6l6 6-6 6-1.41-1.42z'/></svg>");
}
.admonition {
margin: 1.5625em 0;
padding: 0;
overflow: hidden;
color: var(--text-normal);
page-break-inside: avoid;
background-color: var(--background-secondary);
border-left: 0.2rem solid rgb(var(--admonition-color));
border-radius: 0.1rem;
box-shadow: 0 0.2rem 0.5rem var(--background-modifier-box-shadow);
}
.admonition-title {
position: relative;
padding: 0.6rem 0.25em;
font-weight: 700;
background-color: rgba(var(--admonition-color), 0.1);
}
.admonition-title-content {
display: flex;
justify-content: flex-start;
margin-top: 0 !important;
margin-bottom: 0 !important;
}
.admonition-title-icon {
color: rgb(var(--admonition-color));
display: flex;
align-items: center;
justify-content: center;
margin: 0 0.5em 0 0.25em;
min-width: 1em;
}
.admonition-title-markdown {
display: block;
}
.admonition-title.no-title {
display: none;
}
.admonition > .admonition-title.no-title + .admonition-content-holder {
margin-top: 1rem;
margin-bottom: 1rem;
}
.admonition-content-holder {
position: relative;
}
.admonition-content {
margin: 10px 15px;
position: relative;
overflow-x: auto;
}
.admonition-content-copy {
color: var(--text-faint);
cursor: pointer;
opacity: 0;
position: absolute;
right: 0.375rem;
top: -5px;
transition: 0.3s opacity ease-in;
}
.admonition-content-copy:hover {
color: var(--text-normal);
}
.admonition:hover .admonition-content-copy,
.admonition-content-copy:hover {
opacity: 1;
}
.admonition-title:hover + .admonition-content .admonition-content-copy {
opacity: 0;
}
Please note, as of 3.0.0, the admonition colors are no longer set in the CSS.
Each admonition receives the .admonition-<type>
class. You can use this selector to override specific admonition types, but the plugin does not add any styling using this selector by default.
To set the color of admonition types via CSS, specific the following the --admonition-color
variable as an RGB triad:
.admonition-note {
--admonition-color: 68, 138, 255 !important;
}
As of version 6.6, the admonition's parent element also receives classes: .admonition-parent
and .admonition-<type>-parent
.
If an admonition is collapsible, it will receive the following CSS:
details.admonition:not([open]) {
padding-bottom: 0;
}
details.admonition > summary {
outline: none;
list-style: none;
display: block;
min-height: 1rem;
border-top-left-radius: 0.1rem;
border-top-right-radius: 0.1rem;
cursor: pointer;
}
details.admonition > summary::-webkit-details-marker {
display: none;
}
details.admonition > summary > .collapser {
position: absolute;
top: 50%;
right: 8px;
transform: translateY(-50%);
content: "";
}
details.admonition > summary > .collapser > .handle {
transform: rotate(0deg);
transition: transform 0.25s;
background-color: currentColor;
-webkit-mask-repeat: no-repeat;
mask-repeat: no-repeat;
-webkit-mask-size: contain;
mask-size: contain;
-webkit-mask-image: var(--admonition-details-icon);
mask-image: var(--admonition-details-icon);
width: 20px;
height: 20px;
}
details.admonition[open] > summary > .collapser > .handle {
transform: rotate(90deg);
}
An icon without a title will have this CSS:
.admonition-title.no-title {
display: none;
}
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.
See this section for more information.
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.
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.
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.js
file. - Add the contents of the
assets/main.css
file to yourpublish.css
file.
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.
Turns on an experimental mode that uses Obsidian's markdown syntax highlighter inside admonition code blocks.
This will attempt to sync internal links within admonitions to the metadata cache used by Obsidian. This will allow graph view to display these links.
This setting is experimental and could have unintended consequences. If you begin to experience odd behavior, try turning it off and reloading Obsidian.
Allow use of non-codeblock admonitions, described here.
This button will export a JavaScript file to be used on a self-hosted Obsidian Publish site. The generated JavaScript will only be valid for currently defined Admonition types. Any additional types created after generating the file will require a new file to be generated.
Admonitions will be automatically rendered as collapsible (open) by default.
If set, use collapse: none
in an admonition block to override.
This setting is only available if Collapsible By Default is ON
Admonitions will be automatically rendered as opened or closed when collapsible by default.
Adds a "copy content" button to every admonition block.
Commands may be registered for each custom admonition type to insert them into an open note by clicking the Register Commands
button.
Clicking this button will add two commands for that admonition type:
- Insert
- Insert with title
These commands can have hotkeys assigned to them under Settings > Hotkeys.
Registered commands may be removed by clicking on Unregister Commands
.
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
- Added ability to define admonitions without using a code block
- Added
.admonition-plugin
class to top level element - Add command to "Insert Admonition" with a modal chooser
- Add command to "Replace Admonitions with HTML"
- Added RPG Awesome Icons as an option for admonition icons.
- Removed
content
parameter - Fixed some issues related to resolving parameters
- Added ability to register and unregister commands to insert admonitions into a note
- Admonitions that have been created in settings can have commands registered by clicking the new "Register Commands" button
- Registering commands adds two commands:
Insert <type>
andInsert <type> With Title
- Registered commands can be removed by clicking "Unregister Commands"
- Added Sync Links to Metadata Cache setting
- Added Collapsible by Default and Default Collapse Type settings
- Improved Admonition Icon selection experience
- Trimmed whitespace from content when copying to clipboard.
- Added "Copy Button" setting
- Turning this on adds a "copy content" button to each admonition, which copies the admonition content to the clipboard
- Nested admonitions are now possible
- Added commands to open and collapse all admonitions in active note
- Admonition icons now respect the font size of the admonition title
- Collapse handle now centers inside the title element
- CSS changes
- Added a setting to turn on default Obsidian syntax highlighting to admonition code block types
- Admonitions now render titles as Markdown
- Fixed issue where checkboxes in admonitions were not toggleable
- Added ability to create custom admonitions via Settings
- Color, icon, and admonition-type are customizable
- Default admonitions can be overridden by creating a custom admonition of the same type
- Delete the custom admonition to restore default
- To maintain compatibility with other plugins, admonition types must now be prefixed with
ad-
(as in,ad-note
).
- Community plugin release
- Bug fixes
- Uses Obsidian's native markdown renderer to render admonition content
- Removed requirement to use the
content:
tag iftitle:
orcollapse:
is set
- Added
collapse:
parameter to create collapsible admonitions
- Release
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.obsidian
folder may be hidden. On MacOS you should be able to pressCommand+Shift+Dot
to 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!