Skip to content

MkAdmonition

Show source on GitHub

Admonition info box.

Example: Types

Jinja

{{ "Different types." | MkAdmonition(typ="warning") }}

Python

MkAdmonition('Different types.', typ='warning')

Warning

Different types.

!!! warning
    Different types.

<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Different types.</p>
</div>

.. warning:: 
    Different types.

> [!WARNING]> Different types.

MkAdmonition
╰── MkText('Different types.')

Example: Collapsible and expandable

Jinja

{{ "Admonitions can also be collapsible." | MkAdmonition(collapsible=True, title="Expand me!", expanded=True) }}

Python

MkAdmonition(
    "Admonitions can also be collapsible.", title="Expand me!", collapsible=True, expanded=True
)
Expand me!

Admonitions can also be collapsible.

???+ info "Expand me!"
    Admonitions can also be collapsible.

<details class="info" open>
<summary>Expand me!</summary>
<p>Admonitions can also be collapsible.</p>
</details>

.. info:: Expand me!
    Admonitions can also be collapsible.

> [!INFO]> Admonitions can also be collapsible.

MkAdmonition
╰── MkText('Admonitions can also be collapsible.')

Example: Inlined

Jinja

{{ "Inlined" | MkAdmonition(inline="left") }}

Python

MkAdmonition('Inlined', inline='left')

Info

Inlined

!!! info inline
    Inlined

<div class="admonition info inline">
<p class="admonition-title">Info</p>
<p>Inlined</p>
</div>

.. info:: 
    Inlined

> [!INFO]> Inlined

MkAdmonition
╰── MkText('Inlined')

Bases: MkContainer

__init__ 

__init__(
    content: str | list | MkNode,
    *,
    typ: AdmonitionTypeStr | str = "info",
    title: str | None = None,
    collapsible: bool = False,
    expanded: bool = False,
    inline: Literal["left", "right"] | None = None,
    **kwargs: Any
)

Parameters:

Name Type Description Default
content str | list | MkNode

Admonition content

 required
typ AdmonitionTypeStr | str

Admonition type

 'info'
title str | None

Optional Admonition title

 None
collapsible bool

Whether Admontion can get collapsed by user

 False
expanded bool

Initial state if collapsible is set

 False
inline Literal['left', 'right'] | None

Whether admonition should rendered as inline block

 None
kwargs Any

Keyword arguments passed to parent

 {}
Name Children Inherits
MkContainer
mknodes.basenodes.mkcontainer
A node containing other MkNodes.		 
graph TD
  94721311723232["mkadmonition.MkAdmonition"]
  94721311697232["mkcontainer.MkContainer"]
  94721308848336["mknode.MkNode"]
  94721311766592["node.Node"]
  140564252373184["builtins.object"]
  94721311697232 --> 94721311723232
  94721308848336 --> 94721311697232
  94721311766592 --> 94721308848336
  140564252373184 --> 94721311766592
/home/runner/work/mknodes/mknodes/mknodes/basenodes/mkadmonition/metadata.toml
[metadata]
icon = "octicon:info-16"
name = "MkAdmonition"

[requirements.extension.admonition]
[requirements.extension."pymdownx.details"]
[requirements.extension."pymdownx.superfences"]

[examples.annotations]
title = "Annotations"
python = """
import mknodes as mk
node = mk.MkAdmonition("MkAdmonitions can carry annotations(1).")
node.annotations[1] = "Super handy!"
node
"""

[examples.types]
title = "Types"
jinja = """
{{ "Different types." | MkAdmonition(typ="warning") }}
"""

[examples.collapsible]
title = "Collapsible and expandable"
jinja = """
{{ "Admonitions can also be collapsible." | MkAdmonition(collapsible=True, title="Expand me!", expanded=True) }}
"""

[examples.inlined]
title = "Inlined"
jinja = """
{{ "Inlined" | MkAdmonition(inline="left") }}
"""

[output.markdown]
template = """
{% if node.title or node.items %}
{{ node.title_line }}
{{ node.items | join(node.block_separator) | indent(first=True) }}
{% endif %}
"""

[output.block]
template = """
{{ node.fence_boundary }} admonition {{ node.typ }}{{ node.title | add(" | ") }}
{{ node.items | join }}
{{ node.fence_boundary }}
"""

[output.github]
template = """
> [!{{ node.typ | upper }}]\
{{ node.items | join | indent(width="> ", first=True) }}
"""

[output.rst]
template = """
.. {{ node.typ }}:: {{ node.title or "" }}
{{ node.items | join(node.block_separator) | indent(first=True) }}
"""
mknodes.basenodes.mkadmonition.MkAdmonition
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
class MkAdmonition(mkcontainer.MkContainer):
    """Admonition info box."""

    ICON = "octicons/info-16"
    ATTR_LIST_SEPARATOR = "    "
    REQUIRED_EXTENSIONS = [
        resources.Extension("admonition"),
        resources.Extension("pymdownx.details"),
        resources.Extension("pymdownx.superfences"),
    ]

    def __init__(
        self,
        content: str | list | mknode.MkNode,
        *,
        typ: datatypes.AdmonitionTypeStr | str = "info",
        title: str | None = None,
        collapsible: bool = False,
        expanded: bool = False,
        inline: Literal["left", "right"] | None = None,
        **kwargs: Any,
    ):
        """Constructor.

        Args:
            content: Admonition content
            typ: Admonition type
            title: Optional Admonition title
            collapsible: Whether Admontion can get collapsed by user
            expanded: Initial state if collapsible is set
            inline: Whether admonition should rendered as inline block
            kwargs: Keyword arguments passed to parent
        """
        self.typ = typ
        self.title = title
        self.collapsible = collapsible
        self.inline = inline
        self.expanded = expanded
        super().__init__(content=content, **kwargs)

    def attach_annotations(self, text: str) -> str:
        # we deal with attaching annotations ourselves.
        return text

    @property
    def title_line(self):
        block_start = "???" if self.collapsible else "!!!"
        if self.collapsible and self.expanded:
            block_start += "+"
        if self.inline:
            inline_label = " inline" if self.inline == "left" else " inline end"
        else:
            inline_label = ""
        ann_marker = " annotate" if self.annotations else ""
        title = f' "{self.title}"' if self.title is not None else ""
        optional = ann_marker + inline_label
        return f"{block_start} {self.typ}{optional}{title}"

    def _to_markdown(self) -> str:
        if not self.items and not self.title:
            return ""
        annotations = f"\n{self.annotations}\n" if self.annotations else ""
        text = "\n".join(i.to_markdown() for i in self.items)
        indented = textwrap.indent(text, "    ")
        return f"{self.title_line}\n{indented}\n{annotations}"