MkDocs Macros Pluginを使用したカスタムリンクカードを表示するマクロについて¶

概要¶

Mkdocsでカスタムリンクカードを表示するマクロについて記載します。
マクロはMkDocs Macros PluginとJinja2 Template Engineを使用して作成します。

使用方法¶

以下のパラメータをmarkdownに記載することでカスタムリンクカードを追加できます。

パラメータ	必須	デフォルト	説明
`url`	必須	なし	リンク先のURL
`title`	必須	なし	カードのタイトル
`description`	オプション	空文字	カードの説明文
`image_path`	オプション	デフォルト画像	カードに表示する画像
`domain`	オプション	サイトのデフォルトドメイン	ドメイン表示
`external`	オプション	False	外部リンクフラグ
`svg_path`	オプション	URLから自動判定	カスタムSVGアイコンのGistパス

マクロ機能の有効化¶

マクロ機能の有効化手順はmkdocs-macros-utilsに移管しました。
詳細は以下の記事を参照ください。

mkdocs-macros-utils: Link Card

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

7rikazhexde.github.io

使用方法と表示例¶

cssの設定、および、パラメータで指定された値を元にリンクカードを作成します。

サイト内リンクの例¶

最小限のパラメータを指定する方法

Tip

image_pathを省略した場合はassets/img/site.pngを表示します。

{{ link_card(
    url="リンク先のパス",
    title="ページタイトル",
) }}

{{ link_card(
    url="https://7rikazhexde-pkm-obsidian-mkdocs.netlify.app/",
    title="7rikazhexde PKM",
) }}

7rikazhexde PKM

7rikazhexde-pkm-obsidian-mkdocs.netlify.app

GitHub リポジトリリンクの例¶

GitHubのリポジトリへのリンクの場合、デフォルトでGitHubアイコンが自動的に表示されます。
カスタムSVGアイコンを表示したい場合はsvg_pathパラメータにGistのパスを指定します。

GitHubリポジトリを指定する方法

{{ link_card(
    url="GitHub リポジトリのURL",
    title="ページタイトル",
    description="リポジトリの説明",
    domain="github.com/ユーザー名/リポジトリ名",
    external=True
) }}

{{ 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",
    domain="github.com/pyenv-win/pyenv-win",
    external=True
) }}  

pyenv-win Installation Guide

Git installation commands for pyenv-win

github.com/pyenv-win/pyenv-win

カスタムSVGアイコンを指定する方法

SVGファイルについて

以下の形式でgistを作成（public公開）してGistIDとファイル名.svgをlink_cardのパラメーター：svg_pathに指定してください。
特定色（fill="#333" (灰色),fill="black" (黒色))の場合はライトモード、ダークモードの表示を考慮し、class="svg-path"に置換し、class="svg-path"をターゲットにしてCSSで色変更します。

<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>

{{ link_card(
    url="GitHub リポジトリのURL",
    title="ページタイトル",
    description="リポジトリの説明",
    domain="github.com/ユーザー名/リポジトリ名",
    external=True,
    svg_path="ユーザー名/GistID/ファイル名.svg"
) }}

{{ 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.",
    domain="github.com/marketplace/actions/json-to-variables-setter",
    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/marketplace/actions/json-to-variables-setter

はてなブログ記事の例¶

はてなブログの記事へのリンクの場合、はてなブログのロゴが自動的に表示されます。

はてなブログ記事を指定する方法

{{ link_card(
    url="はてなブログの記事URL",
    title="ページタイトル",
    description="記事の説明",
    domain="ユーザー名.hatenablog.com",
    external=True  
) }}

{{ 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="Ubuntu on RaspberryPi上にPyenvとPoetryを使用してPython環境を構築する",
    description="Ubuntu on RaspberryPi上にPyenvとPoetryを使用してPython環境を構築する手順を解説",
    domain="7rikazhexde-techlog.hatenablog.com/entry/2023/07/08/173536",
    external=True
) }}  

Ubuntu on RaspberryPi上にPyenvとPoetryを使用してPython環境を構築する

Ubuntu on RaspberryPi上にPyenvとPoetryを使用してPython環境を構築する手順を解説

7rikazhexde-techlog.hatenablog.com/entry/2023/07/08/173536

その他のWebサイトの例¶

上記以外のWebサイトの場合はデフォルトでは画像は表示されません。

その他のWebサイトを指定する方法

{{ link_card(
    url="サイトのURL",  
    title="ページタイトル",
    description="ページの説明",
    external=True  
) }}

{{ link_card(
    url="https://news.mynavi.jp/techplus/article/zeropython-122/",
    title="ゼロからのPython入門講座",
    description="Pythonプログラミングの基礎を解説している連載講座",
    domain="news.mynavi.jp/techplus/article/zeropython-122/",
    external=True
) }}

ゼロからのPython入門講座

Pythonプログラミングの基礎を解説している連載講座

news.mynavi.jp/techplus/article/zeropython-122/

トラブルシューティング¶

パスが正しいか確認
マクロプラグイン(mkdocs-macros-utils)をインストール、および、configファイル(mkdocs.yml)を正しく設定されているか確認
テンプレートファイルの存在を確認(docs/includes/link-card.html)
外部リンクの場合はexternal=Trueが設定されているか確認