Skip to content

MkLink

Show source on GitHub

Description

If no title is given, the URL is used as a title.

Example: Regular

Jinja

{{ "https://www.google.com" | MkLink("This is a link") }}

Python

MkLink('https://www.google.com', 'This is a link')

This is a link

[This is a link](https://www.google.com)

<p><a href="https://www.google.com">This is a link</a></p>

`This is a link <https://www.google.com>`_

Example: Button

Jinja

{{ "https://www.google.com" | MkLink("Disguised as button.", as_button=True) }}

Python

MkLink('https://www.google.com', 'Disguised as button.', as_button=True)

Disguised as button.

[Disguised as button.](https://www.google.com){: .md-button}

<p><a class="md-button" href="https://www.google.com">Disguised as button.</a></p>

`Disguised as button. <https://www.google.com>`_

Example: Colored

Jinja

{{ "https://www.google.com" | MkLink("Colored.", as_button=True, primary_color=True) }}

Python

MkLink('https://www.google.com', 'Colored.', as_button=True, primary_color=True)

Colored.

[Colored.](https://www.google.com){: .md-button .md-button--primary}

<p><a class="md-button md-button--primary" href="https://www.google.com">Colored.</a></p>

`Colored. <https://www.google.com>`_

Example: With icon

Jinja

{{ "https://www.google.com" | MkLink("With icon.", icon="octicon:link-24") }}

Python

MkLink('https://www.google.com', 'With icon.', icon='octicon:link-24')

With icon.

[:octicon-link-24: With icon.](https://www.google.com)

<p><a href="https://www.google.com"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="currentColor" d="M14.78 3.653a3.936 3.936 0 1 1 5.567 5.567l-3.627 3.627a3.936 3.936 0 0 1-5.88-.353a.75.75 0 0 0-1.18.928a5.436 5.436 0 0 0 8.12.486l3.628-3.628a5.436 5.436 0 1 0-7.688-7.688l-3 3a.75.75 0 0 0 1.06 1.061z"/><path fill="currentColor" d="M7.28 11.153a3.936 3.936 0 0 1 5.88.353a.75.75 0 0 0 1.18-.928a5.436 5.436 0 0 0-8.12-.486L2.592 13.72a5.436 5.436 0 1 0 7.688 7.688l3-3a.75.75 0 1 0-1.06-1.06l-3 3a3.936 3.936 0 0 1-5.567-5.568z"/></svg></span> With icon.</a></p>

`With icon. <https://www.google.com>`_

Example: With tooltip

Jinja

{{ "https://www.google.com" | MkLink("With tooltip.", as_button=True) }}

Python

MkLink('https://www.google.com', 'With tooltip.', as_button=True)

With tooltip.

[With tooltip.](https://www.google.com){: .md-button}

<p><a class="md-button" href="https://www.google.com">With tooltip.</a></p>

`With tooltip. <https://www.google.com>`_

Bases: MkNode

__init__ 

__init__(
    target: LinkableType,
    title: str | None = None,
    *,
    tooltip: str | None = None,
    icon: str | None = None,
    as_button: bool = False,
    primary_color: bool = False,
    **kwargs: Any
)

Parameters:

Name Type Description Default
target LinkableType

Link target

 required
title str | None

Title used for link

 None
tooltip str | None

Tooltip for the link

 None
icon str | None

Optional icon to be displayed in front of title

 None
as_button bool

Whether link should be rendered as button

 False
primary_color bool

If rendered as button, use primary color as background.

 False
kwargs Any

keyword arguments passed to parent

 {}

for_pydantic_playground classmethod 

for_pydantic_playground(
    files: Mapping[str, str] | list[ModuleType] | Sequence[str | PathLike[str]],
    title: str = "Open in Pydantic Playground",
    active_index: int = 0,
    **kwargs: Any
) -> MkLink

Parameters:

Name Type Description Default
files Mapping[str, str] | list[ModuleType] | Sequence[str | PathLike[str]]

The files to include in the playground. Can be: - A mapping of filenames to code content - A list of modules - A list of file paths

 required
title str

The title of the link

 'Open in Pydantic Playground'
active_index int

The index of the active file in the playground

 0
**kwargs Any

Additional keyword arguments to pass to the Pydantic playground

 {}
Name Children Inherits
MkNode
mknodes.basenodes.mknode
Base class for everything which can be expressed as Markup.		 
graph TD
  94272697810736["mklink.MkLink"]
  94272697820320["mknode.MkNode"]
  94272697777776["node.Node"]
  139836355973312["builtins.object"]
  94272697820320 --> 94272697810736
  94272697777776 --> 94272697820320
  139836355973312 --> 94272697777776
/home/runner/work/mknodes/mknodes/mknodes/basenodes/mklink/metadata.toml
[metadata]
icon = "octicon:link-24"
name = "MkLink"

[examples.regular]
title = "Regular"
jinja = """
{{ "https://www.google.com" | MkLink("This is a link") }}
"""

[examples.button]
title = "Button"
jinja = """
{{ "https://www.google.com" | MkLink("Disguised as button.", as_button=True) }}
"""

[examples.colored]
title = "Colored"
jinja = """
{{ "https://www.google.com" | MkLink("Colored.", as_button=True, primary_color=True) }}
"""

[examples.with_icon]
title = "With icon"
jinja = """
{{ "https://www.google.com" | MkLink("With icon.", icon="octicon:link-24") }}
"""

[examples.with_tooltip]
title = "With tooltip"
jinja = """
{{ "https://www.google.com" | MkLink("With tooltip.", as_button=True) }}
"""
# [examples.to_page]
# title = "To Page"
# jinja = """
# {{ page.parent.index_page | MkLink("To page.") }}
# """

[output.markdown]
template = """
[{{ node.icon | add(suffix=" ") }}{{ node.title }}]({{ node.url }}{{ node.tooltip | add(prefix=" '", suffix="'")}})
"""

[output.rst]
template = """
`{{ node.title }} <{{ node.url }}>`_
"""
mknodes.basenodes.mklink.MkLink
 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
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
class MkLink(mknode.MkNode):
    """A simple Link (with optional icon and option to show up as a button).

    If no title is given, the URL is used as a title.
    """

    ICON = "octicons/link-24"
    ATTR_LIST_SEPARATOR = ""

    def __init__(
        self,
        target: linkprovider.LinkableType,
        title: str | None = None,
        *,
        tooltip: str | None = None,
        icon: str | None = None,
        as_button: bool = False,
        primary_color: bool = False,
        **kwargs: Any,
    ):
        """Constructor.

        Args:
            target: Link target
            title: Title used for link
            tooltip: Tooltip for the link
            icon: Optional icon to be displayed in front of title
            as_button: Whether link should be rendered as button
            primary_color: If rendered as button, use primary color as background.
            kwargs: keyword arguments passed to parent
        """
        super().__init__(**kwargs)
        self.target = target
        self._title = title
        self.tooltip = tooltip
        self.as_button = as_button
        self.primary_color = primary_color
        self._icon = icon
        if as_button:
            self.add_css_class("md-button")
        if primary_color:
            self.add_css_class("md-button--primary")

    @property
    def icon(self) -> str:
        return icons.get_emoji_slug(self._icon) if self._icon else ""

    @property
    def url(self) -> str:
        return self.ctx.links.get_url(self.target)

    @property
    def title(self) -> str:
        return self._title or self.url

    @classmethod
    def for_pydantic_playground(
        cls,
        files: Mapping[str, str]
        | list[types.ModuleType]
        | Sequence[str | os.PathLike[str]],
        title: str = "Open in Pydantic Playground",
        active_index: int = 0,
        **kwargs: Any,
    ) -> MkLink:
        """Create a link to Pydantic playground with pre-populated files.

        Args:
            files: The files to include in the playground. Can be:
                    - A mapping of filenames to code content
                    - A list of modules
                    - A list of file paths
            title: The title of the link
            active_index: The index of the active file in the playground
            **kwargs: Additional keyword arguments to pass to the Pydantic playground

        Returns:
            An MkLink instance pointing to the Pydantic playground
        """
        from urllib.parse import quote

        match files:
            case Mapping():
                file_data: list[dict[str, Any]] = [
                    {"name": name, "content": content} for name, content in files.items()
                ]
            case [types.ModuleType(), *_]:
                file_data = [
                    {"name": f"{mod.__name__}.py", "content": inspect.getsource(mod)}  # type: ignore
                    for mod in files
                ]
            case [str() | os.PathLike(), *_]:
                file_data = []
                for path in files:
                    file = upath.UPath(path)
                    file_data.append({
                        "name": file.name,
                        "content": file.read_text("utf-8"),
                    })
            case _:
                raise TypeError(files)

        # Add activeIndex to first file
        if file_data:
            file_data[active_index]["activeIndex"] = 1

        json_str = json.dumps(file_data)
        encoded = quote(json_str)

        url = f"https://pydantic.run/new?files={encoded}"
        return cls(url, title, **kwargs)

    def _to_markdown(self) -> str:
        prefix = f"{self.icon} " if self.icon else ""
        tooltip = f" {self.tooltip!r}" if self.tooltip else ""
        return f"[{prefix}{self.title}]({self.url}{tooltip})"