Feature: Configurable admonitions

[joapuiib]

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"

[joapuiib]

I'm waiting for feedback in this discussion in order to know the steps to follow.

[joapuiib]

@jaywhj Was this closed because of the main branch rename?

I think if it's open I can change the target branch in order to preserve this PR.

[jaywhj]

@joapuiib Could be.

After renaming, the master branch has been deleted by me.
You may try this in sequence:

git checkout <your-PR−branch>
git fetch upstream
git rebase upstream/main
git push --force-with-lease

You can keep your current PR branch, no need to create a new one.

Just rebase it onto main, this will update the PR automatically.

[jaywhj]

Additionally, I have a few questions regarding the code implementation that we could discuss together:

1. Since this is a custom implementation, is it necessary to distinguish default_types? Would a unified override logic be more appropriate?
2. There is a bug in the style concatenation (malformed structure), resulting in an extra closing brace } in the final output. This line {% set _.style = _.style ~ "}\u003c/style\u003e" %}

Below is a reference version with the proposed changes. Please evaluate whether this approach is feasible, or feel free to iterate further on top of it.

<!-- Custom admonition icons -->
{% if config.theme.admonition %}
  {% set _ = namespace(root_list = [], class_list = []) %}

  {% for type, keys in config.theme.admonition | items %}
    {# ---------- root ---------- #}
    {% if keys.icon is defined and keys.icon %}
      {% import ".icons/" ~ keys.icon ~ ".svg" as icon %}
      {% set icon_svg = icon | replace("\n", "") | urlencode %}
      {% set _.root_list = _.root_list + [
        "--md-admonition-icon--" ~ type ~
        ":url('data:image/svg+xml;charset=utf-8," ~ icon_svg ~ "');"
      ] %}
    {% endif %}

    {% if keys.color is defined and keys.color %}
      {% set _.root_list = _.root_list + [
        "--md-admonition-color--" ~ type ~ ":" ~ keys.color ~ ";"
      ] %}
    {% endif %}

    {# ---------- class ---------- #}
    {% set rules = [] %}

    {% if keys.icon is defined and keys.icon %}
      {% set rules = rules + [
        "--md-admonition-icon:var(--md-admonition-icon--" ~ type ~ ");"
      ] %}
    {% endif %}

    {% if keys.color is defined and keys.color %}
      {% set rules = rules + [
        "--md-admonition-color:var(--md-admonition-color--" ~ type ~ ");"
      ] %}
    {% endif %}

    {% if rules | length %}
      {% set rule_str = rules | join("") %}
      {% set selector =
        ".md-typeset .admonition." ~ type ~
        ",.md-typeset details." ~ type
      %}
      {% set _.class_list = _.class_list + [
        selector ~ "{" ~ rule_str ~ "}"
      ] %}
    {% endif %}

  {% endfor %}

  {% set root = ":root{" ~ (_.root_list | join("")) ~ "}" %}
  {% set classes = _.class_list | join("") %}
  {{ ("\u003cstyle\u003e" ~ root ~ classes ~ "\u003c/style\u003e") | safe }}
{% endif %}

[joapuiib]

@jaywhj But, can you reopen the PR so I try to change the target branch from master to main? If not, I'll open a new PR.

---

Since this is a custom implementation, is it necessary to distinguish default_types? Would a unified override logic be more appropriate?

Class-specific admonition styles rules are already defined in src/templates/assets/stylesheets/main/extensions/markdown/_admonition.scss:

// Admonition flavour - sets color and icon variables for each type
@each $name, $props in $admonitions {
  .md-typeset .admonition.#{$name} {
    --md-admonition-color: var(--md-admonition-color--#{$name});
    --md-admonition-icon: var(--md-admonition-icon--#{$name});
  }
}

When overriding a bundled admonition color/icon, if we don't control that, the rules will be duplicated.

---

Regarding your proposed changes.

You use a list instead of a string in order to concatenate variables and style-rules.
Is there a specific reason for it?

---

Edit: I've updated the code to integrate your variable handling suggestions but keep it a string.

[jaywhj]

Let me check how this should be handled. The Reopen button is also grayed out and disabled on my end.
I didn’t close it manually; it was all handled automatically by GitHub.

[joapuiib]

@jaywhj Ok, I'll open a new PR.