Skip to content

About the macro to display custom link cards using the MkDocs Macros Plugin

Summary

This section describes a macro to display custom link cards in Mkdocs.

This macro is assumed to be used with Material for Mkdocs.

Usage

Custom link cards can be added by including a macro in markdown with the following parameters

Macro name: link_card.

Parameters Required Default Description
url required None Linked URL
title required None Card Title
description optional blank text card description
image_path optional default image image to display on card
domain optional Default domain of the site Domain Display
external optional False external link flag
svg_path optional Automatic determination from URL Custom SVG icon path in format "user_id/gist_id/filename" (e.g., "7rikazhexde/d418315080179e7c1bd9a7a4366b81f6/github-cutom-icon.svg")

Exapmples

Create a link card based on the css settings and the values specified in the parameters.

How to specify minimum parameters

Tip

If image_path is omitted, assets/img/site.png will be displayed.

1
2
3
4
{{ link_card(
    url="Linked path (absolute path)",
    title="page title",
) }}

1
2
3
4
{{ link_card(
    url="https://7rikazhexde.github.io/mkdocs-macros-utils/",
    title="MkDocs Macros Utils Documentation",
) }}
MkDocs Macros Utils Documentation
7rikazhexde.github.io
MkDocs Macros Utils Documentation

For links to GitHub repositories, the GitHub icon is automatically displayed by default. If you want to display a custom SVG icon, specify the Gist path in the svg_path parameter.

How to specify a GitHub repository 
1
2
3
4
5
6
{{ link_card(
    url="GitHub repository URL",
    title="Page title",
    description="Repository description",
    external=True
) }}

1
2
3
4
5
6
{{ link_card(
    url="https://github.com/pyenv-win/pyenv-win/blob/master/docs/installation.md#git-commands",
    title="pyenv-win Installation Guide",
    description="Git installation commands for pyenv-win",
    external=True
) }}
pyenv-win Installation Guide
Git installation commands for pyenv-win
github.com
How to designate SVG as the icon for card links

About the SVG file to be used

  • Create a gist in the following format (public release) and specify the GistID and filename.svg in the link_card parameter: svg_path.
  • In case of specific colors (fill="#333" (gray),fill="black" (black)), replace with class="svg-path" considering light mode and dark mode display, and change colors by CSS targeting class="svg-path".
1
2
3
<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128">
    <path fill="#2088ff" d="M26.666 0C11.97 0 0 11.97 0 26.666c0 12.87 9.181 23.651 21.334 26.13v37.87c0 11.77 9.68 21.334 21.332 21.334h.195c1.302 9.023 9.1 16 18.473 16C71.612 128 80 119.612 80 109.334s-8.388-18.668-18.666-18.668c-9.372 0-17.17 6.977-18.473 16h-.195c-8.737 0-16-7.152-16-16V63.779a18.514 18.514 0 0 0 13.24 5.555h2.955c1.303 9.023 9.1 16 18.473 16 9.372 0 17.169-6.977 18.47-16h11.057c1.303 9.023 9.1 16 18.473 16 10.278 0 18.666-8.39 18.666-18.668C128 56.388 119.612 48 109.334 48c-9.373 0-17.171 6.977-18.473 16H79.805c-1.301-9.023-9.098-16-18.471-16s-17.171 6.977-18.473 16h-2.955c-6.433 0-11.793-4.589-12.988-10.672 14.58-.136 26.416-12.05 26.416-26.662C53.334 11.97 41.362 0 26.666 0zm0 5.334A21.292 21.292 0 0 1 48 26.666 21.294 21.294 0 0 1 26.666 48 21.292 21.292 0 0 1 5.334 26.666 21.29 21.29 0 0 1 26.666 5.334zm-5.215 7.541C18.67 12.889 16 15.123 16 18.166v17.043c0 4.043 4.709 6.663 8.145 4.533l13.634-8.455c3.257-2.02 3.274-7.002.032-9.045l-13.635-8.59a5.024 5.024 0 0 0-2.725-.777zm-.117 5.291 13.635 8.588-13.635 8.455V18.166zm40 35.168a13.29 13.29 0 0 1 13.332 13.332A13.293 13.293 0 0 1 61.334 80 13.294 13.294 0 0 1 48 66.666a13.293 13.293 0 0 1 13.334-13.332zm48 0a13.29 13.29 0 0 1 13.332 13.332A13.293 13.293 0 0 1 109.334 80 13.294 13.294 0 0 1 96 66.666a13.293 13.293 0 0 1 13.334-13.332zm-42.568 6.951a2.667 2.667 0 0 0-1.887.78l-6.3 6.294-2.093-2.084a2.667 2.667 0 0 0-3.771.006 2.667 2.667 0 0 0 .008 3.772l3.974 3.96a2.667 2.667 0 0 0 3.766-.001l8.185-8.174a2.667 2.667 0 0 0 .002-3.772 2.667 2.667 0 0 0-1.884-.78zm48 0a2.667 2.667 0 0 0-1.887.78l-6.3 6.294-2.093-2.084a2.667 2.667 0 0 0-3.771.006 2.667 2.667 0 0 0 .008 3.772l3.974 3.96a2.667 2.667 0 0 0 3.766-.001l8.185-8.174a2.667 2.667 0 0 0 .002-3.772 2.667 2.667 0 0 0-1.884-.78zM61.334 96a13.293 13.293 0 0 1 13.332 13.334 13.29 13.29 0 0 1-13.332 13.332A13.293 13.293 0 0 1 48 109.334 13.294 13.294 0 0 1 61.334 96zM56 105.334c-2.193 0-4 1.807-4 4 0 2.195 1.808 4 4 4s4-1.805 4-4c0-2.193-1.807-4-4-4zm10.666 0c-2.193 0-4 1.807-4 4 0 2.195 1.808 4 4 4s4-1.805 4-4c0-2.193-1.807-4-4-4zM56 108c.75 0 1.334.585 1.334 1.334 0 .753-.583 1.332-1.334 1.332-.75 0-1.334-.58-1.334-1.332 0-.75.585-1.334 1.334-1.334zm10.666 0c.75 0 1.334.585 1.334 1.334 0 .753-.583 1.332-1.334 1.332-.75 0-1.332-.58-1.332-1.332 0-.75.583-1.334 1.332-1.334z"/><path fill="#79b8ff" d="M109.334 90.666c-9.383 0-17.188 6.993-18.477 16.031a2.667 2.667 0 0 0-.265-.011l-2.7.09a2.667 2.667 0 0 0-2.578 2.751 2.667 2.667 0 0 0 2.752 2.578l2.7-.087a2.667 2.667 0 0 0 .097-.006C92.17 121.029 99.965 128 109.334 128c10.278 0 18.666-8.388 18.666-18.666s-8.388-18.668-18.666-18.668zm0 5.334a13.293 13.293 0 0 1 13.332 13.334 13.29 13.29 0 0 1-13.332 13.332A13.293 13.293 0 0 1 96 109.334 13.294 13.294 0 0 1 109.334 96z"/>
</svg>

1
2
3
4
5
6
7
{{ link_card(
    url="GitHub repository URL",
    title="Page title",
    description="Repository description",
    external=True,
    svg_path="UserID/GistID/sample.svg"
) }}

1
2
3
4
5
6
7
{{ link_card(
    url="https://github.com/marketplace/actions/json-to-variables-setter",
    title="JSON to Variables Setter",
    description="GitHub Action designed to parse a JSON file and set the resulting variables (such as operating systems, programming language versions, and GitHub Pages branch) as outputs in a GitHub Actions workflow.",
    external=True,
    svg_path="7rikazhexde/996eec6799c869324bf9fe2e93b1a876/github-actions-icon.svg"
) }}
JSON to Variables Setter
GitHub Action designed to parse a JSON file and set the resulting variables (such as operating systems, programming language versions, and GitHub Pages branch) as outputs in a GitHub Actions workflow.
github.com

Example of a Hatena blog post

If the link is to a Hatena Blog post, the Hatena Blog logo will automatically be displayed.

How to specify a Hatena blog post 
1
2
3
4
5
6
7
{{ link_card(
    url="Hatena blog post URL",
    title="Page title",
    description="Article description",
    domain="username.hatenablog.com",
    external=True
) }}

1
2
3
4
5
6
{{ link_card(
    url="https://7rikazhexde-techlog.hatenablog.com/entry/2023/07/08/173536#Pyenv%E3%81%AB%E3%82%88%E3%82%8BPython%E7%92%B0%E5%A2%83%E3%82%92%E6%A7%8B%E7%AF%89%E3%81%99%E3%82%8B",
    title="Building a Python environment on Ubuntu on RaspberryPi using Pyenv and Poetry",
    description="Explanation of how to build a Python environment using Pyenv and Poetry on Ubuntu on RaspberryPi.",
    external=True
) }}
Building a Python environment on Ubuntu on RaspberryPi using Pyenv and Poetry
Explanation of how to build a Python environment using Pyenv and Poetry on Ubuntu on RaspberryPi.
7rikazhexde-techlog.hatenablog.com

Other Web site examples

For websites other than those listed above, icons are not displayed on card links by default.

How to specify other Web sites 
1
2
3
4
5
6
{{ link_card(
    url="URL of the site",
    title="page title",
    description="page description",
    external=True
) }}

1
2
3
4
5
6
{{ link_card(
    url="https://news.mynavi.jp/techplus/article/zeropython-122/",
    title="Introduction to Python from scratch",
    description="A series of courses explaining the basics of Python programming",
    external=True
) }}
Introduction to Python from scratch
A series of courses explaining the basics of Python programming
news.mynavi.jp