# obsidian-admonition: styled callouts, custom icons and two ways to write them

> The Admonition plugin for Obsidian adds attention-grabbing blocks to notes, with built-in types such as tip, warning, caution and note, a library of icons, custom CSS, and both a callout syntax and a fenced block syntax. It is MIT licensed, at version 12.0.10, and it ships a beta manifest alongside the stable one.

**ebullient/obsidian-admonition** — Adds admonition block-styled content to Obsidian.md 

- Repository: https://github.com/ebullient/obsidian-admonition
- Stars: 1,346 · Forks: 88
- Language: TypeScript
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/ebullient-obsidian-admonition

## Two syntaxes for the same visual block

The plugin is described as a tool for creating attention-grabbing callouts, tips, warnings and other informative blocks within notes, and it gives you two ways to write one.

The first is the callout version, where you type the name of an admonition type such as >[!tip] followed by your content. The second is the admonition version, where you open a code block with a type marker such as ad-tip and put your content on the following lines, closing it with three backticks. The README's example shows the second form carrying a title, and the content lines look like this:

```yaml
title: This is a tip

This is the content of the admonition tip.
```

The distinction matters more than it looks. The callout form is the syntax Obsidian itself understands, so a note written that way still renders as a callout for a reader who has no plugins installed, and the admonition form is a richer block that carries a title and can be styled independently.

That is the design in one sentence: the plugin works with Obsidian's callouts and extends them, rather than replacing them with a format only the plugin can read. The quickstart is five steps, ending with previewing the note to see the formatted admonition, and the full instructions and examples are in the docs directory.

## Icons, CSS and the two selectors to target

The plugin provides a range of pre-defined icons to pick from, and the ability to create your own custom styles using CSS. Both are the point of the tool. Obsidian's own callouts come with a fixed set of types and icons, and the styling is whatever the theme decides, so a vault that wants a distinct visual language for warnings needs a plugin precisely because the built-in feature cannot do it.

The README gives the mechanism for targeting things precisely: you can target each iteration independently using the .callout and .admonition selectors. Two selectors, one for each of the two syntaxes, means a stylesheet can treat a callout and an admonition separately, and a specific admonition type can be addressed without disturbing the rest.

Styling can go two ways, and the README lists both. You can use Markdown attributes in callouts, which means the style travels with the note, or you can style directly with CSS, which means it lives in your theme or a snippet and applies everywhere. The attribute route is the portable one, and it is the route that survives a vault being shared with someone whose theme is different.

## Built-in types, nesting and template integration

The feature list names the built-in admonition types, including tip, warning, caution and note, and among them, so the useful cases are covered without any configuration.

Two capabilities are about composition rather than appearance. The plugin supports nesting of blockquotes and code blocks, so an admonition can contain a quotation or a snippet and the structure holds together. And the plugin is meant to work with other plugins: the README says admonitions can flourish in combination with Obsidian's own Templates plugin or with Templater by SilentVoid13, which is the practical route to generating a callout from a template without typing the syntax by hand.

The last feature is portability of your own work. Admonitions can be imported and exported via .json files, so a set of custom types, with their icons and their styles, can be defined once and then shared with a team or carried to another vault. For anyone who has hand-built a set of callout types in a snippet, that export is the difference between a personal convention and something the rest of a team can use.

## Building it: esbuild, biome and generated icon sets

The package.json shows a plugin that treats its icons and its formatting as generated artefacts rather than hand-maintained files. The devDependencies include the Font Awesome core packages for solid, regular and brand icons, the Octicons set, and a script that generates the icon assets:

```json
"gen-icons": "node icons/fas/_gen.js && node icons/far/_gen.js && node icons/fab/_gen.js && node icons/fa-names/_gen.js && node icons/octicons/_gen.js",
"dev": "node ./esbuild.config.mjs",
"build": "node ./esbuild.config.mjs production",
"lint": "npx @biomejs/biome lint ./src",
```

So there is a whole icons/ directory in the repository, with separate subdirectories per icon set, and the plugin can offer icons from several libraries without the author hand-copying a few thousand SVG files. The build itself is esbuild, and the lint and format tooling is Biome, with ESLint also present through an eslint.config.mjs and the eslint-plugin-obsidianmd rules.

The changelog is generated too. The version script runs auto-changelog with a Handlebars template from .github/changelog.hbs, and the configuration includes an ignore pattern for commit messages that are about changelogs, releases or README updates, plus a text replacement rule that strips trailing issue numbers from Resolves and Fixes entries. That is a small sign of a project with a large number of small releases, which the release list confirms.

## Where the plugin is the wrong choice

The first wrong-tool case is a vault where Obsidian's own callouts are already enough. Callouts with the built-in types cover the common case of marking a tip or a warning, and they render identically in Obsidian, in the app on the phone and in most Markdown viewers that understand the callout syntax. Adding a plugin to get what the built-in feature already provides is a dependency without a benefit, and it costs a reader who does not have the plugin something.

The second is a publishing workflow outside Obsidian. A note that relies on the admonition fenced syntax is a note that renders as a code block in any other tool. If a vault is published to a website, exported to PDF, or read in a Markdown viewer, the fences need to be converted, and the plugin is not part of that pipeline.

The third is a shared vault where styling is governed centrally. Because the custom styles are CSS targeting .callout and .admonition, a theme or snippet change in a shared vault can restyle every admonition in every note at once. That is a feature when one person owns the look and a problem when several people do, and the README does not describe a mechanism for scoping a custom style to one note or one folder.

## MIT, version 12.0.10, and a beta manifest in the tree

The plugin is MIT licensed, with the LICENSE file at the repository root and the licence declared in the package metadata. The repository is not archived, and the last push was on 2026-10-15.

The version history shows a project shipping very frequently. Version 12.0.10 was released on 2026-10-06, 12.0.9 on the same day a little earlier, and 12.0.8 on 2026-10-01. Three releases in the first week of October, all patch releases on the same minor line, is the pattern of an actively maintained plugin that fixes small things as they appear.

The numbering is also worth a note. A plugin at version 12 with no recent major bump is a project that has been through a lot of renames of its own feature set, and the major number is a poor guide to how much the thing has changed in a given release. The CHANGELOG.md at the root, generated by auto-changelog, is the reliable history.

The presence of manifest-beta.json next to manifest.json shows a second, experimental channel shipped from the same tree, and the versions.json file tracks plugin versions. There is also a publish/ directory, an ad-test-vault/ directory used as a test fixture, and a svelte.config.js, which indicates that parts of the settings interface are written with Svelte.

## Conclusion

Adopt obsidian-admonition if your notes are shared and you want callouts that render the same way for a reader who does not have the plugin, since the callout syntax is the one Obsidian itself understands, and use the admonition syntax when you need the richer metadata. Do not adopt it if your vault already looks right with Obsidian's built-in callouts and you have no need for custom icons or per-admonition CSS, and do not adopt the fenced admonition syntax in notes you expect to read outside Obsidian. Before you commit, read the docs directory for the custom admonition format, check the beta manifest to see which features are still considered experimental, and note that custom styles and icons are defined with the .callout and .admonition selectors, so a theme change can change how your notes look.

## FAQ

### How do I write an admonition in obsidian-admonition?

In callout form, type the type marker such as >[!tip] followed by the content. In admonition form, open a fenced block with a type marker such as ad-tip, add the content on the following lines, and close it with three backticks. The README shows an admonition block carrying a title line.

### What is the difference between the callout and admonition syntax?

The callout form uses the syntax Obsidian itself understands, so it still renders for a reader without the plugin. The admonition form is a fenced block that can carry a title and richer metadata, and it renders as a code block in tools that do not know the plugin.

### How do I style custom admonitions in obsidian-admonition?

The plugin provides pre-defined icons to pick from and lets you add your own styles with CSS, and the README says you can target each iteration independently with the .callout and .admonition selectors. You can also use Markdown attributes in callouts so the styling travels with the note.

### Can I share my custom admonitions with other people?

Yes. The plugin supports import and export of custom admonitions via .json files, so a set of custom types with their icons and styles can be moved between vaults or shared with a team.

### What is the current version of obsidian-admonition?

The package metadata lists 12.0.10, and the release list shows 12.0.10 from 2026-10-06, 12.0.9 from the same day and 12.0.8 from 2026-10-01. The repository also ships a manifest-beta.json alongside the standard manifest.

## Sources

- [ebullient/obsidian-admonition on GitHub](https://github.com/ebullient/obsidian-admonition)
- [Issues](https://github.com/ebullient/obsidian-admonition/issues)
- [License: MIT](https://github.com/ebullient/obsidian-admonition/blob/main/LICENSE)
- [README](https://github.com/ebullient/obsidian-admonition/blob/main/README.md)
- [Releases](https://github.com/ebullient/obsidian-admonition/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ebullient-obsidian-admonition