Skip to content

MkDocs Macros Guide

This document explains the custom macros available for Symphony by data-conductor.com blog posts.

Available Macros

1. hero_quote

Creates a hero section with an image and blockquote side-by-side.

Syntax: 

{{ hero_quote(image_path, quote_text, alt_text) }}

Parameters: - image_path (required): Path to image relative to /img/ directory - quote_text (required): The quote content (can be multi-line) - alt_text (optional): Alt text for the image. If not provided, auto-generated from filename

Examples:

Simple usage: 

{{ hero_quote(
  "2025/DataIsNewOil.png",
  "Data is the new oil — a phrase that's been repeated so often it risks losing meaning."
) }}

With custom alt text: 

{{ hero_quote(
  "diagrams/data-pipeline.png",
  "Building robust data pipelines requires more than just connecting the dots.",
  "Modern Data Pipeline Architecture"
) }}

Multi-line quote: 

{{ hero_quote(
  "charts/growth-metrics.png",
  """Data-driven organizations are 23 times more likely to acquire customers
  and 19 times more likely to be profitable than those that aren't.""",
  "Business Growth Metrics"
) }}

2. image_card

Creates a card with image, title, and description.

Syntax: 

{{ image_card(image_path, title, description, link, alt_text) }}

Parameters: - image_path (required): Path to image - title (required): Card title - description (required): Card description - link (optional): URL to link the card to - alt_text (optional): Alt text for image

Example: 

{{ image_card(
  "tools/airflow-logo.png",
  "Apache Airflow",
  "Workflow orchestration platform for data engineering pipelines",
  "https://airflow.apache.org/"
) }}

3. callout_box

Creates a styled callout box for important information.

Syntax: 

{{ callout_box(content, type, title) }}

Parameters: - content (required): The content of the callout - type (optional): info, warning, success, error (default: info) - title (optional): Optional title for the callout

Examples:

Info callout: 

{{ callout_box(
  "Remember to always backup your data before major transformations.",
  "info",
  "Best Practice"
) }}

Warning callout: 

{{ callout_box(
  "This operation will permanently delete all historical data.",
  "warning",
  "Caution Required"
) }}

4. tech_stack_grid

Creates a grid of technology badges.

Syntax: 

{{ tech_stack_grid("tech1", "tech2", "tech3") }}

Parameters: - Variable number of technology names as strings

Example: 

{{ tech_stack_grid("Python", "Apache Spark", "PostgreSQL", "Docker", "Kubernetes", "Apache Kafka") }}

Usage Tips

Image Paths

  • Images should be placed in the /docs/img/ directory
  • You can organize them in subdirectories (e.g., 2025/, diagrams/, charts/)
  • Paths in macros should be relative to /img/ (e.g., "2025/my-image.png")

Quote Formatting

  • Use triple quotes """ for multi-line quotes
  • Escape single quotes with \' when needed
  • The macro automatically handles basic formatting

Responsive Design

  • All macros are designed to be responsive
  • They work well on both desktop and mobile devices
  • Images automatically scale appropriately

Styling

  • Macros use CSS variables for theming (light/dark mode compatible)
  • Colors and spacing are consistent with Material theme
  • Styles are inline to avoid dependencies on external CSS files

Example Blog Post Structure

---
title: "My Blog Post"
date: 2025-10-11
authors:
  - author_name
categories:
  - Technology
tags:
  - data-engineering
---

{{ hero_quote(
  "2025/hero-image.png",
  "This is the opening quote that sets the tone for the entire article."
) }}

Your introduction content here...

{{ callout_box(
  "Important information that readers should pay attention to.",
  "info",
  "Key Insight"
) }}

More content...

{{ tech_stack_grid("Python", "Apache Spark", "Docker") }}

{{ image_card(
  "tools/example-tool.png",
  "Example Tool",
  "Description of this amazing tool we're discussing.",
  "https://example-tool.com"
) }}

Conclusion content...

Troubleshooting

Macro Not Working

  1. Ensure the mkdocs-macros-plugin is installed
  2. Check that macros is listed in your mkdocs.yml plugins
  3. Verify the main.py file is in your project root
  4. Check for syntax errors in your macro calls

Image Not Displaying

  1. Verify the image exists in /docs/img/
  2. Check the file path is correct (case-sensitive)
  3. Ensure image format is supported (PNG, JPG, SVG, etc.)

Quotes Not Formatting Correctly

  1. Use triple quotes for multi-line content
  2. Escape special characters properly
  3. Check for unmatched quotes in your content