Skip to content

About macros to generate Gist code blocks using MkDocs Macros Plugin

Summary

This section describes a macro that displays Gist code in a Mkdocs code block.

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

Usage

Write a macro in markdown with the following parameters to display Gist code in a code block.

Macro：gist_codeblock

Parameters Required Default Description
gist_url required none Gist shared link
indent optional 0 indent level (0: none, 1: 4 spaces, 2: 8 spaces)
ext Optional Automatic determination from URL language extension (e.g. py, js, sh, etc.)

Examples

Basic Usage

Specify minimal parameters 
1
2
3
{{ gist_codeblock(
    gist_url="https://gist.github.com/user/id"
) }}

Example

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
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
#!/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

Specify indentation level

Tip

Must be specified if the code is to be displayed within a block of admonition.

Specify indentation level 
1
2
3
4
{{ gist_codeblock(
    gist_url="Gist shared link",
    indent=1  # Indentation level (1:4 spaces, 2:8 spaces)
) }}

Example of displaying code within an admonition block

1
2
3
4
5
6
??? info "Title"

    {{ gist_codeblock(
        gist_url="https://gist.github.com/7rikazhexde/89036d5fc849411b925e6da7d4986b52",
        indent=2
    ) }}
Indent example (indent=1) 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
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
#!/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 example (indent=2) 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
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
#!/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

To explicitly specify a language

Specify language extensions 
1
2
3
4
{{ gist_codeblock(
    gist_url="Gist shared link",
    ext="py"  # Specify language extensions
) }}

Example

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
#!/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