Whitecloud Blog

Whitecloud Blog

Markdown Custom Directive Guide
0%
· 5 min read

Markdown Custom Directive Guide

Markdown Custom Directive Complete Guide

This document demonstrates how to use all custom directive syntax in regular .md files. These directives provide enhanced visual components without requiring MDX.

1. Admonitions

Admonitions (also called callouts or alerts) help highlight important information. Each type has a distinct color scheme and icon.

Available Types

Note

Use for neutral information that deserves attention.

Note

Note: This highlights information that users should take into account, even when skimming. Great for additional context or related information.

Tip

Use for helpful suggestions or best practices.

Tip

Pro Tip: Optional information to help users be more successful. Use this for shortcuts, efficiency tips, or expert recommendations.

Important

Use for critical information that requires immediate attention.

Important

Important: Crucial information that directly impacts the user’s workflow or results. Missing this could lead to errors or suboptimal outcomes.

Warning

Use for potential issues or cautionary information.

Warning

Warning: Information about potential risks or complications. Users should proceed with caution and awareness of possible consequences.

Caution

Use for serious warnings about dangerous actions.

Caution

Caution: Critical warnings about actions that could cause data loss, security issues, or system problems. Users must read this before proceeding.

Syntax

:::note
Your note content here
:::


:::tip
Your tip content here
:::
> [!NOTE]
> GitHub syntax


> [!TIP]
> GitHub syntax

The Gallery directive creates an interactive image carousel with navigation controls. Users can browse through images by clicking left/right arrows or using keyboard navigation.

Syntax

:::gallery
image-url-1
image-url-2
image-url-3
:::

Features

  • Responsive Design: Automatically adapts to screen size
  • Navigation Controls: Left/Right arrows for browsing
  • Keyboard Support: Use arrow keys to navigate
  • Lightbox Effect: Click to view images in full size

Example

Usage Tips

  • Each line inside the directive should contain a single image URL
  • Supports both absolute URLs and relative paths
  • Works with .jpg, .png, .webp, and .gif formats
  • Recommended minimum width: 640px for best quality

3. ImageGrid (Grid Layout)

The ImageGrid directive creates a responsive grid layout for multiple images. Perfect for photo galleries, portfolios, or product showcases.

Syntax

:::imagegrid
image-url-1
image-url-2
image-url-3
image-url-4
:::

Example

Usage Tips

  • Best with 3, 6, or 9 images for perfect grid alignment
  • All images should have similar aspect ratios for best results
  • Supports any number of images, but multiples of 3 work best on desktop

4. FullpageImage (Full-Width Image)

The FullpageImage directive creates a dramatic full-width image that spans the entire viewport width, perfect for hero sections or visual breaks in content.

Syntax

:::fullpage-image{src="image-url"}
:::

Features

  • Full Viewport Width: Stretches edge-to-edge
  • Responsive Height: Maintains aspect ratio
  • High Impact: Creates visual emphasis
  • Scroll Integration: Smoothly integrates with page flow

Example

Usage Tips

  • Use high-resolution images (minimum 1920px width recommended)
  • Best for landscape-oriented images
  • Consider page loading time with large images
  • Use for visual breaks between content sections

5. FullpageImageContent (Full-Width Image with Text Overlay)

The FullpageImageContent directive combines a full-width image with centered text overlay. The image is automatically darkened to ensure text readability.

Syntax

:::fullpage-image-content{src="image-url"}


# Your Heading


Your paragraph text here


:::

Features

  • Automatic Image Darkening: 40% dark overlay for text readability
  • Centered Content: Text is vertically and horizontally centered
  • Markdown Support: Use any markdown formatting inside
  • Responsive Typography: Text scales appropriately on different screens

Example

Explore the Ocean

Experience the tranquility and beauty of the sea. Dive into a world of wonder and discover the depths beneath.