Skip to content

mkdocs-macros-utils

mkdocs-macros-utils is mkdocs-macros-plugin based project that provides macros to extend cards, code blocks, etc, in MkDocs documents.

Features

  • Link Card: Create link cards with images and descriptions, etc
  • Gist Code Block: Embed and syntax-highlight code from GitHub Gists
  • X/Twitter Card: Embed tweets with proper styling and dark mode support

Usage

Install mkdocs-macros-utils

For pip

1
pip install mkdocs-macros-utils

For poetry

1
poetry add mkdocs-macros-utils

Config settings

  1. Add the plugin to your mkdocs.yml

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
    plugins:
  - macros:
      modules: [mkdocs_macros_utils]

markdown_extensions:
  - attr_list
  - md_in_html

extra:
  debug:
    link_card: false  # Set to true for debug logging
    gist_codeblock: false
    x_twitter_card: false

extra_css:
  - stylesheets/macros-utils/link-card.css
  - stylesheets/macros-utils/gist-cb.css
  - stylesheets/macros-utils/x-twitter-link-card.css

extra_javascript:
  - javascripts/macros-utils/x-twitter-widget.js

  2. Start the development server

    1
    poetry run mkdocs serve

The plugin will automatically create the required directories and copy CSS/JS files during the build process.

Examples