MkDocs Macros Pluginを使用したGistのコードブロックを生成するマクロについて¶

概要¶

MkdocsでGistのコードを直接取得して表示するマクロについて記載します。
マクロはMkDocs Macros Pluginを使用して作成します。

使用方法¶

以下のパラメータをmarkdownに記載することでGistのコードブロックを追加できます。

パラメータ	必須	デフォルト	説明
`gist_url`	必須	なし	Gistの共有リンク
`indent`	オプション	0	インデントレベル（`0`: なし、`1`: 4スペース、`2`: 8スペース）
`ext`	オプション	URLから自動判定	言語拡張子（例：`py`, `js`, `sh`など）

マクロ機能の有効化¶

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

mkdocs-macros-utils: Gist Code Block

About macros to generate Gist code blocks using MkDocs Macros Plugin

7rikazhexde.github.io

使用方法と表示例¶

GistのURLとオプションパラメータを指定して、コードブロックを生成します。

基本的な使用方法¶

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

{{ gist_codeblock(
    gist_url="https://gist.github.com/user/id"
) }}

実例:

{{ gist_codeblock(
    gist_url="https://gist.github.com/7rikazhexde/89036d5fc849411b925e6da7d4986b52"
) }}

#!/usr/bin/env bash

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

create_post_commit() {
    cat > "$1" << EOF
#!/usr/bin/env bash

source "$SCRIPT_DIR/../.venv/bin/activate"
poetry run python "$SCRIPT_DIR/../ci/run_git_tag_base_pyproject.py"
if [ $? -ne 0 ]; then
    printf "Error occurred in run_git_tag_base_pyproject.py. Exiting post-commit.\n"
    exit 1
fi

git push origin main:main
git push --tags
printf ".git/hooks/post-commit end!!!\n"
EOF

    if [ "$2" == "execute" ]; then
        chmod +x "$1"
        echo "$1 created with execution permission."
    else
        echo "$1 created."
    fi
}

if [ -f "$SCRIPT_DIR/.git/hooks/post-commit" ]; then
    # For shellcheck SC2162
    read -r -p "$SCRIPT_DIR/../.git/hooks/post-commit already exists. Do you want to create $SCRIPT_DIR/.git/hooks/post-commit.second instead? (y/N): " choice
    if [[ $choice == "y" || $choice == "Y" ]]; then
        create_post_commit "$SCRIPT_DIR/../.git/hooks/post-commit.second"
        exit 0
    else
        create_post_commit "$SCRIPT_DIR/../.git/hooks/post-commit" "execute"
        exit 0
    fi
fi

create_post_commit "$SCRIPT_DIR/../.git/hooks/post-commit" "execute"
exit 0

インデントレベルを指定する場合¶

Tip

admonitionのブロック内でコードを表示する場合に指定する必要があります。

インデントレベルを指定する方法

{{ gist_codeblock(
    gist_url="Gistの共有リンク",
    indent=1  # インデントレベル（1=4スペース、2=8スペース）
) }}

admonitionブロック内でコードを表示する例：

??? info "タイトル"

    {{ gist_codeblock(
        gist_url="https://gist.github.com/7rikazhexde/89036d5fc849411b925e6da7d4986b52",
        indent=1
    ) }}

インデント例(indent=1)

#!/usr/bin/env bash

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

create_post_commit() {
    cat > "$1" << EOF
#!/usr/bin/env bash

source "$SCRIPT_DIR/../.venv/bin/activate"
poetry run python "$SCRIPT_DIR/../ci/run_git_tag_base_pyproject.py"
if [ $? -ne 0 ]; then
    printf "Error occurred in run_git_tag_base_pyproject.py. Exiting post-commit.\n"
    exit 1
fi

git push origin main:main
git push --tags
printf ".git/hooks/post-commit end!!!\n"
EOF

    if [ "$2" == "execute" ]; then
        chmod +x "$1"
        echo "$1 created with execution permission."
    else
        echo "$1 created."
    fi
}

if [ -f "$SCRIPT_DIR/.git/hooks/post-commit" ]; then
    # For shellcheck SC2162
    read -r -p "$SCRIPT_DIR/../.git/hooks/post-commit already exists. Do you want to create $SCRIPT_DIR/.git/hooks/post-commit.second instead? (y/N): " choice
    if [[ $choice == "y" || $choice == "Y" ]]; then
        create_post_commit "$SCRIPT_DIR/../.git/hooks/post-commit.second"
        exit 0
    else
        create_post_commit "$SCRIPT_DIR/../.git/hooks/post-commit" "execute"
        exit 0
    fi
fi

create_post_commit "$SCRIPT_DIR/../.git/hooks/post-commit" "execute"
exit 0

インデント例(indent=2)

#!/usr/bin/env bash

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

create_post_commit() {
    cat > "$1" << EOF
#!/usr/bin/env bash

source "$SCRIPT_DIR/../.venv/bin/activate"
poetry run python "$SCRIPT_DIR/../ci/run_git_tag_base_pyproject.py"
if [ $? -ne 0 ]; then
    printf "Error occurred in run_git_tag_base_pyproject.py. Exiting post-commit.\n"
    exit 1
fi

git push origin main:main
git push --tags
printf ".git/hooks/post-commit end!!!\n"
EOF

    if [ "$2" == "execute" ]; then
        chmod +x "$1"
        echo "$1 created with execution permission."
    else
        echo "$1 created."
    fi
}

if [ -f "$SCRIPT_DIR/.git/hooks/post-commit" ]; then
    # For shellcheck SC2162
    read -r -p "$SCRIPT_DIR/../.git/hooks/post-commit already exists. Do you want to create $SCRIPT_DIR/.git/hooks/post-commit.second instead? (y/N): " choice
    if [[ $choice == "y" || $choice == "Y" ]]; then
        create_post_commit "$SCRIPT_DIR/../.git/hooks/post-commit.second"
        exit 0
    else
        create_post_commit "$SCRIPT_DIR/../.git/hooks/post-commit" "execute"
        exit 0
    fi
fi

create_post_commit "$SCRIPT_DIR/../.git/hooks/post-commit" "execute"
exit 0

言語を明示的に指定する場合¶

言語を指定する方法

{{ gist_codeblock(
    gist_url="Gistの共有リンク",
    ext="py"  # 言語拡張子を指定
) }}

実例:

{{ gist_codeblock(
    gist_url="https://gist.github.com/7rikazhexde/6ada2a6ef3ca23938bfa62f32e3fbed8",
    ext="sh"
) }}

#!/usr/bin/env bash
# Usage: poetry install pre-commit install
# File generated by pre-commit: https://pre-commit.com

# start templated
INSTALL_PYTHON=[Project Path]/.venv/bin/python
ARGS=(hook-impl --config=.pre-commit-config.yaml --hook-type=pre-commit)
# end templated

HERE="$(cd "$(dirname "$0")" && pwd)"
ARGS+=(--hook-dir "$HERE" -- "$@")

if [ -x "$INSTALL_PYTHON" ]; then
    exec "$INSTALL_PYTHON" -mpre_commit "${ARGS[@]}"
elif command -v pre-commit > /dev/null; then
    exec pre-commit "${ARGS[@]}"
else
    echo '`pre-commit` not found.  Did you forget to activate your virtualenv?' 1>&2
    exit 1
fi

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

マクロプラグイン(mkdocs-macros-utils)がインストール、および、configファイル(mkdocs.yml)が正しく設定されているか確認
GistのURLが正しいか確認
インデントレベルを使用する場合、適切な値（0, 1, 2, ..., n）が設定されているか確認
言語拡張子を指定する場合、サポートされている拡張子が使用されているか確認