Skip to content

Feature: Configurable admonitions - #27

Merged
jaywhj merged 6 commits into
jaywhj:mainfrom
joapuiib:feat/configurable-theme-admonitions
Apr 5, 2026
Merged

jaywhj merged 6 commits into
jaywhj:mainfrom
joapuiib:feat/configurable-theme-admonitions

Conversation

@joapuiib

@joapuiib joapuiib commented Apr 4, 2026

Copy link
Copy Markdown
Contributor

This PR adds the ability to configure custom admonition styles from mkdocs|properdocs.yml.

theme:
  admonition:
    git:
      icon: simple/git
      color: "#f34f29"
    pied-piper:
      icon: fontawesome/brands/pied-piper-alt
      color: "#2b9b46"
image

Previous work and discussions:

@jaywhj

jaywhj commented Apr 4, 2026

Copy link
Copy Markdown
Owner

@joapuiib

I still suggest the following:

Now that we've refactored the way custom admonitions are implemented, users should be able to customize admonitions in the simplest and most intuitive way.
If a user configures the system default admonitions in mkdocs.yml, those settings should directly override the defaults. This is a very explicit and intentional action on the user’s part, indicating they want to adjust the styling of the system default admonitions.

Otherwise, configuring or customizing admonitions would require handling them differently in separate places, which would unnecessarily raise the barrier to entry.

@joapuiib

joapuiib commented Apr 4, 2026 •

Copy link
Copy Markdown
Contributor Author

@jaywhj

This solution also allows users to override theme's defaults, since it does override the :root variables for all types.

The only difference is that the CSS rules for built-in classes are not defined twice.


theme:
  admonition:
    example:
      color: '#ff9800'
image

@joapuiib

joapuiib commented Apr 4, 2026 •

Copy link
Copy Markdown
Contributor Author

For this config:

  admonition:
    git:
      icon: simple/git
      color: '#f34f29'
    example:
      color: '#ff9800'

Injected styles:

<style>
  :root{
    --md-admonition-icon--git:url('data:image/svg+xml;charset=utf-8,%3Csvg%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%20viewBox%3D%220%200%2024%2024%22%3E%3Cpath%20d%3D%22M23.546%2010.93%2013.067.452a1.55%201.55%200%200%200-2.188%200L8.708%202.627l2.76%202.76a1.838%201.838%200%200%201%202.327%202.341l2.658%202.66a1.838%201.838%200%200%201%201.9%203.039%201.837%201.837%200%200%201-2.6%200%201.85%201.85%200%200%201-.404-1.996L12.86%208.955v6.525c.176.086.342.203.488.348a1.85%201.85%200%200%201%200%202.6%201.844%201.844%200%200%201-2.609%200%201.834%201.834%200%200%201%200-2.598c.182-.18.387-.316.605-.406V8.835a1.834%201.834%200%200%201-.996-2.41L7.636%203.7.45%2010.881c-.6.605-.6%201.584%200%202.189l10.48%2010.477a1.545%201.545%200%200%200%202.186%200l10.43-10.43a1.544%201.544%200%200%200%200-2.187%22/%3E%3C/svg%3E');
    --md-admonition-color--git:#f34f29;
    --md-admonition-color--example:#ff9800;
  }
  .md-typeset .admonition.git,.md-typeset details.git {
    --md-admonition-icon:var(--md-admonition-icon--git);
    --md-admonition-color:var(--md-admonition-color--git);
  }
</style>
  • git admonition has :root variables and .admonition.git css rules.
  • example admonition (as is buit-in) only needs to override :root variables.

@joapuiib

joapuiib commented Apr 4, 2026 •

Copy link
Copy Markdown
Contributor Author

You can try it with:

git remote add joapuiib https://github.com/joapuiib/mkdocs-materialx.git
git fetch joapuiib
git checkout joapuiib/feat/configurable-theme-admonitions
npm start && properdocs serve --watch-theme # In separate terminals

@jaywhj

jaywhj commented Apr 4, 2026

Copy link
Copy Markdown
Owner

Okay, I'll give it a try in a bit.

@DevTwilight

Copy link
Copy Markdown

looks cool

@DevTwilight

Copy link
Copy Markdown

can conform it is working

@jaywhj

jaywhj commented Apr 4, 2026

Copy link
Copy Markdown
Owner

@joapuiib

Alright, create the PR!

@joapuiib

joapuiib commented Apr 4, 2026

Copy link
Copy Markdown
Contributor Author

@jaywhj
Do you want me to update the docs or do you want to do it?

I'd include both ways of costumization: config-based and css overriding.

@jaywhj

jaywhj commented Apr 4, 2026

Copy link
Copy Markdown
Owner

@joapuiib

Then it would be great if you could update the documentation.
After all, as the developer of this feature, you’re more familiar with the actual usage scenarios.

@joapuiib
joapuiib marked this pull request as ready for review April 4, 2026 17:45
@joapuiib

joapuiib commented Apr 4, 2026

Copy link
Copy Markdown
Contributor Author

@jaywhj

Done. Please reaview it and tell me if you want to make any change.

@jaywhj

jaywhj commented Apr 5, 2026

Copy link
Copy Markdown
Owner

@jaywhj

Done. Please reaview it and tell me if you want to make any change.

Nice work.

There’s one more document that needs adjusting: line 105 in
docs/setup/changing-the-logo-and-icons.md

Change admonitions.md#admonition-icons
to admonitions.md#custom-icons-and-colors

@jaywhj
jaywhj merged commit 268eeda into jaywhj:main Apr 5, 2026
@joapuiib
joapuiib deleted the feat/configurable-theme-admonitions branch April 6, 2026 10:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants