Skip to content

feat: data-driven custom admonitions #42

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
banteg wants to merge 3 commits into from
Closed

feat: data-driven custom admonitions #42

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
813dda2
feat(admonitions): style custom types from extra
banteg Jan 13, 2026
35dc961
fix(ui): harden custom admonition styles
banteg Jan 14, 2026
92947fc
fix: make custom admonition templates minijinja-safe
banteg Jan 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 109 additions & 6 deletions dist/partials/icons.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,124 @@
{#-
This file was automatically generated - do not edit
-#}
{% if config.theme.icon.admonition %}
{% set _ = namespace(style = "\u003cstyle\u003e:root{") %}
{% for type, icon in config.theme.icon.admonition | items %}
{% if type and icon %}
{% set admonition_icons = config.theme.icon.admonition | d({}, true) %}
{% set admonition_extra = config.extra.admonitions | d({}, true) %}
{% set ns = namespace(types = []) %}
{% if admonition_icons is mapping %}
{% for type, icon in admonition_icons | items %}
{% if type and icon and type not in ns.types %}
{% set ns.types = ns.types + [type] %}
{% endif %}
{% endfor %}
{% endif %}
{% if admonition_extra is mapping %}
{% for type, data in admonition_extra | items %}
{% if type and type not in ns.types %}
{% if data is mapping %}
{% set has_data = data.icon or data.color %}
{% else %}
{% set has_data = data %}
{% endif %}
{% if has_data %}
{% set ns.types = ns.types + [type] %}
{% endif %}
{% endif %}
{% endfor %}
{% endif %}
{% if ns.types %}
{% set _ = namespace(style = "\u003cstyle\u003e:root{", has_icon = false) %}
{% for type in ns.types %}
{% if admonition_extra is mapping and type in admonition_extra %}
{% set data = admonition_extra[type] %}
{% else %}
{% set data = None %}
{% endif %}
{% if data is mapping %}
{% set icon = data.icon %}
{% elif data %}
{% set icon = data %}
{% else %}
{% set icon = None %}
{% endif %}
{% if not icon and admonition_icons is mapping and type in admonition_icons %}
{% set icon = admonition_icons[type] %}
{% endif %}
{% if icon %}
{% import ".icons/" ~ icon ~ ".svg" as icon %}
{% set _.style = _.style ~
"--md-admonition-icon--" ~ type ~ ":" ~
"url('data:image/svg+xml;charset=utf-8," ~
icon | replace("\n", "") | urlencode ~
"');"
%}
{% set _.has_icon = true %}
{% endif %}
{% endfor %}
{% set _.style = _.style ~ "}\u003c/style\u003e" %}
{{ _.style }}
{% if _.has_icon %}
{% set _.style = _.style ~ "}\u003c/style\u003e" %}
{{ _.style }}
{% endif %}
{% endif %}
{% if ns.types %}
<style>
{% for type in ns.types %}
{% if admonition_extra is mapping and type in admonition_extra %}
{% set data = admonition_extra[type] %}
{% else %}
{% set data = None %}
{% endif %}
{% if data is mapping %}
{% set color = data.color %}
{% set icon = data.icon %}
{% elif data %}
{% set color = None %}
{% set icon = data %}
{% else %}
{% set color = None %}
{% set icon = None %}
{% endif %}
{% if not icon and admonition_icons is mapping and type in admonition_icons %}
{% set icon = admonition_icons[type] %}
{% endif %}
{% if color %}
{% if config.theme.variant == "modern" %}
.md-typeset :is(.admonition, details).{{ type }} {
background-color: color-mix(in srgb, {{ color }} 10%, transparent);
border-color: {{ color }};
}
.md-typeset :is(.admonition, details).{{ type }}:focus-within {
box-shadow: 0 0 0 0.25rem color-mix(in srgb, {{ color }} 10%, transparent);
}
{% else %}
.md-typeset :is(.admonition, details).{{ type }} {
border-color: {{ color }};
}
.md-typeset :is(.admonition, details).{{ type }}:focus-within {
box-shadow: 0 0 0 0.25rem color-mix(in srgb, {{ color }} 10%, transparent);
}
.md-typeset .{{ type }} > .admonition-title {
background-color: color-mix(in srgb, {{ color }} 10%, transparent);
}
{% endif %}
{% endif %}
{% if color or icon %}
.md-typeset .{{ type }} > .admonition-title::before {
{% if color %}
background-color: {{ color }};
{% endif %}
{% if icon %}
-webkit-mask-image: var(--md-admonition-icon--{{ type }});
mask-image: var(--md-admonition-icon--{{ type }});
{% endif %}
}
{% endif %}
{% if color %}
.md-typeset .{{ type }} > .admonition-title::after {
color: {{ color }};
}
{% endif %}
{% endfor %}
</style>
{% endif %}
{% if config.theme.icon.annotation %}
{% set _ = namespace(style = "\u003cstyle\u003e:root{") %}
Expand Down
119 changes: 113 additions & 6 deletions src/partials/icons.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,22 +23,129 @@
IN THE SOFTWARE.
-->

{% set admonition_icons = config.theme.icon.admonition | d({}, true) %}
{% set admonition_extra = config.extra.admonitions | d({}, true) %}

{% set ns = namespace(types = []) %}
{% if admonition_icons is mapping %}
{% for type, icon in admonition_icons | items %}
{% if type and icon and type not in ns.types %}
{% set ns.types = ns.types + [type] %}
{% endif %}
{% endfor %}
{% endif %}
{% if admonition_extra is mapping %}
{% for type, data in admonition_extra | items %}
{% if type and type not in ns.types %}
{% if data is mapping %}
{% set has_data = data.icon or data.color %}
{% else %}
{% set has_data = data %}
{% endif %}
{% if has_data %}
{% set ns.types = ns.types + [type] %}
{% endif %}
{% endif %}
{% endfor %}
{% endif %}

<!-- Custom admonition icons -->
{% if config.theme.icon.admonition %}
{% set _ = namespace(style = "\u003cstyle\u003e:root{") %}
{% for type, icon in config.theme.icon.admonition | items %}
{% if type and icon %}
{% if ns.types %}
{% set _ = namespace(style = "\u003cstyle\u003e:root{", has_icon = false) %}
{% for type in ns.types %}
{% if admonition_extra is mapping and type in admonition_extra %}
{% set data = admonition_extra[type] %}
{% else %}
{% set data = None %}
{% endif %}
{% if data is mapping %}
{% set icon = data.icon %}
{% elif data %}
{% set icon = data %}
{% else %}
{% set icon = None %}
{% endif %}
{% if not icon and admonition_icons is mapping and type in admonition_icons %}
{% set icon = admonition_icons[type] %}
{% endif %}
{% if icon %}
{% import ".icons/" ~ icon ~ ".svg" as icon %}
{% set _.style = _.style ~
"--md-admonition-icon--" ~ type ~ ":" ~
"url('data:image/svg+xml;charset=utf-8," ~
icon | replace("\n", "") | urlencode ~
"');"
%}
{% set _.has_icon = true %}
{% endif %}
{% endfor %}
{% set _.style = _.style ~ "}\u003c/style\u003e" %}
{{ _.style }}
{% if _.has_icon %}
{% set _.style = _.style ~ "}\u003c/style\u003e" %}
{{ _.style }}
{% endif %}
{% endif %}

<!-- Custom admonition styles -->
{% if ns.types %}
<style>
{% for type in ns.types %}
{% if admonition_extra is mapping and type in admonition_extra %}
{% set data = admonition_extra[type] %}
{% else %}
{% set data = None %}
{% endif %}
{% if data is mapping %}
{% set color = data.color %}
{% set icon = data.icon %}
{% elif data %}
{% set color = None %}
{% set icon = data %}
{% else %}
{% set color = None %}
{% set icon = None %}
{% endif %}
{% if not icon and admonition_icons is mapping and type in admonition_icons %}
{% set icon = admonition_icons[type] %}
{% endif %}
{% if color %}
{% if config.theme.variant == "modern" %}
.md-typeset :is(.admonition, details).{{ type }} {
background-color: color-mix(in srgb, {{ color }} 10%, transparent);
border-color: {{ color }};
}
.md-typeset :is(.admonition, details).{{ type }}:focus-within {
box-shadow: 0 0 0 0.25rem color-mix(in srgb, {{ color }} 10%, transparent);
}
{% else %}
.md-typeset :is(.admonition, details).{{ type }} {
border-color: {{ color }};
}
.md-typeset :is(.admonition, details).{{ type }}:focus-within {
box-shadow: 0 0 0 0.25rem color-mix(in srgb, {{ color }} 10%, transparent);
}
.md-typeset .{{ type }} > .admonition-title {
background-color: color-mix(in srgb, {{ color }} 10%, transparent);
}
{% endif %}
{% endif %}
{% if color or icon %}
.md-typeset .{{ type }} > .admonition-title::before {
{% if color %}
background-color: {{ color }};
{% endif %}
{% if icon %}
-webkit-mask-image: var(--md-admonition-icon--{{ type }});
mask-image: var(--md-admonition-icon--{{ type }});
{% endif %}
}
{% endif %}
{% if color %}
.md-typeset .{{ type }} > .admonition-title::after {
color: {{ color }};
}
{% endif %}
{% endfor %}
</style>
{% endif %}

<!-- Custom annotation icon -->
Expand Down