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

Installation

Currently, the package can be installed from GitHub using Poetry:

  1. Add the dependency to your project's pyproject.toml

    1
2
3
4
    [project]
dependencies = [
    "mkdocs-macros-utils@git+https://github.com/7rikazhexde/mkdocs-macros-utils.git@main"
]

    or

    1
    poetry add "mkdocs-macros-utils@git+https://github.com/7rikazhexde/mkdocs-macros-utils.git@main"

    I plan to make this package available via pip in the future.

    To reflect the latest code, remove mkdocs-macros-utils once and then add it again.

    1
2
    poetry remove mkdocs-macros-utils
poetry add "mkdocs-macros-utils@git+https://github.com/7rikazhexde/mkdocs-macros-utils.git#main"

  2. Install using Poetry

    1
    poetry install

Usage

  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