Admonitions should have box, color and icon

[axolotl-git]

Describe the feature

right now the admonitions look like this:

which look very wrong

Use Case

because it's a good way to make users notice the admonition and look less ugly

Proposed Solution

i'd like if it looked like this (with ofc the colors and theme of dracula):

Other Information

the admonition markdown look like this:

!!! warning "WIP"

    **the docs are still a WIP and may not be 100% correct**

i also tried

!!! warning "WIP"
    **the docs are still a WIP and may not be 100% correct**

to be sure

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

SDK version used

mkdocs-dracula-theme 1.0.8 with mkdocs 1.6.1 on Python 3.13

Environment details (OS name and version, etc.)

Windows 11

[axolotl-git]

maybe something like this?

here the CSS:

.admonition{
	box-sizing:content-box;
	background: #282a36;
	width: 41.4%;
	padding: 25px 20px 15px 20px;
	border-radius: var(--rounded-lg);
	border-style: solid;
	border-width: 5px;
	border-color: #ff5555;
	border-left-width: 13.5px;
}
.admonition-title{
	padding-left: 60px;
	transform: scale(1.3);
}
.admonition.warning .admonition-title{
		color: #ff5555
}

[FernandoCelmer]

Review: Admonitions Should Have Box, Color, and Icon

Summary

This request asks for proper visual styling of MkDocs admonition blocks (e.g., !!! warning) within the Dracula theme. Currently, admonitions render as unstyled or near-invisible blocks — lacking a colored border, background, and the icon in the title row that make them immediately recognizable. The reporter confirmed the issue on mkdocs-dracula-theme 1.0.8 with MkDocs 1.6.1 and already prototyped a CSS-only fix in a follow-up comment.

---

Analysis

Relevance: High. Admonitions are a first-class MkDocs Markdown feature used extensively in technical documentation. A theme that ships without admonition styles forces every user to add custom CSS just to get readable warnings/notes/tips — a poor out-of-the-box experience.

Root cause: mkdocs.min.css (the theme's own stylesheet, ~5.9 KB) contains no .admonition or .admonition-title rules at all. MkDocs itself generates the HTML structure with the appropriate classes, but styling is entirely the theme's responsibility.

Complexity: Low-to-medium. The HTML structure is already emitted correctly by MkDocs. This is purely a CSS addition; no changes to Jinja templates or Python code are required.

Current status: Open, labeled pending + feature-request. No existing rules to conflict with; the field is blank.

---

Implementation Options

Option 1 — Minimal targeted patch (recommended baseline)

Add a focused .admonition block to mkdocs.min.css (or its source file) covering the most common admonition types (warning, note, tip, danger, info). Use Dracula palette variables already defined in dracula-ui.min.css (--purple, --pink, --cyan, --green, --yellow, --red, --orange) for border and title colors, matching one type per color.

.admonition {
  background: #282a36;
  border-radius: 4px;
  border-left: 6px solid #6272a4;
  padding: 1rem 1.25rem 0.75rem;
  margin: 1.5rem 0;
}
.admonition-title {
  font-weight: 700;
  margin-bottom: 0.5rem;
  padding-left: 1.75rem;
  position: relative;
}
/* Per-type accent colors using Dracula palette */
.admonition.warning  { border-left-color: #ffb86c; }
.admonition.warning .admonition-title  { color: #ffb86c; }
.admonition.danger   { border-left-color: #ff5555; }
.admonition.danger  .admonition-title  { color: #ff5555; }
.admonition.tip      { border-left-color: #50fa7b; }
.admonition.tip     .admonition-title  { color: #50fa7b; }
.admonition.note     { border-left-color: #8be9fd; }
.admonition.note    .admonition-title  { color: #8be9fd; }
.admonition.info     { border-left-color: #bd93f9; }
.admonition.info    .admonition-title  { color: #bd93f9; }

Trade-offs: quick to ship, zero template changes, covers the common cases. Requires adding Font Awesome icon pseudo-elements (FA is already loaded via CDN in base.html) if icons are desired.

---

Option 2 — Option 1 + Font Awesome icons in titles

Extend Option 1 with ::before pseudo-elements on .admonition-title using Font Awesome glyph codes already available (the theme loads FA 4.7 unconditionally). This matches the visual the reporter proposed.

.admonition-title::before {
  font-family: "FontAwesome";
  position: absolute;
  left: 0;
  font-size: 1.1em;
}
.admonition.warning .admonition-title::before { content: "\f071"; } /* fa-exclamation-triangle */
.admonition.danger  .admonition-title::before { content: "\f06d"; } /* fa-fire */
.admonition.tip     .admonition-title::before { content: "\f0eb"; } /* fa-lightbulb-o */
.admonition.note    .admonition-title::before { content: "\f040"; } /* fa-pencil */
.admonition.info    .admonition-title::before { content: "\f05a"; } /* fa-info-circle */

Trade-offs: best visual result with no new dependencies (FA is already loaded). Slightly more CSS to maintain.

---

Option 3 — Expose an extra_css workaround in the docs

Document a copy-paste snippet in docs/nav/getting-started.md that users can drop into their own extra_css file. No code changes to the theme itself.

Trade-offs: zero maintenance burden, ships immediately. Does not fix the problem for the default experience; every user must opt in manually. Only viable as a short-term bridge while Options 1/2 land.

---

Option 4 — Introduce a source CSS file and build step

Replace the current hand-edited mkdocs.min.css with a source .css file (or SCSS) that gets minified on release. Add admonitions as a proper section in that source.

Trade-offs: the cleanest long-term architecture, but requires introducing a build step. Overkill for this fix alone; worth considering if the project plans to grow its custom CSS.

---

Recommendation

Ship Option 2 (border + per-type accent colors + Font Awesome icons). It requires only adding ~40 lines of CSS to mkdocs.min.css, leverages the Font Awesome dependency that is already unconditionally loaded in base.html, uses existing Dracula palette CSS variables, and produces the visual result the reporter demoed. No template changes, no new dependencies, no breaking changes.

The reporter's prototype is a solid starting point; the main adjustments needed before merging are:

1. Replace the hardcoded #ff5555 hex values with the corresponding Dracula CSS variable references (e.g., var(--red), var(--orange)) so the colors stay consistent with the rest of the theme.
2. Drop the width: 41.4% constraint — admonitions should be full-width and flow naturally within the content column.
3. Add the remaining admonition types (note, tip, info, success, abstract, question, bug, example, quote) with appropriate Dracula color mappings.

Happy to submit a PR with the full CSS block if that's helpful.