How to Create Custom Markdown Image Directives with Centering and Dimensions in Astro

Use astro-big-doc's built-in directive system to extend Markdown syntax with :::image blocks that support center, width, and height attributes for precise layout control.

Creating custom markdown image directives allows you to enrich standard Markdown with component-like behavior without leaving the document format. The microwebstacks/astro-big-doc repository implements a lightweight directive architecture that parses custom syntax and routes it to specialized Astro components, giving you full control over image rendering, alignment, and sizing.

Understanding the Directive Architecture

The directive system centers on two core files that handle parsing and dispatching. src/components/markdown/AstroMarkdown.astro serves as the entry point, processing Markdown content and detecting textDirective nodes. These nodes are then forwarded to src/components/markdown/directive/Directive.astro, which acts as a router, mapping directive names to specific implementation components.

<!-- src/components/markdown/directive/Directive.astro -->
import ImageDirective from './ImageDirective.astro';
// import ImageDirective from './OptimizedImageDirective.astro';
...
<ImageDirective node={node} dirpath={dirpath}/>

By default, the dispatcher imports ImageDirective, but you can switch to OptimizedImageDirective by uncommenting the alternative import and commenting out the plain version.

Built-in Image Directives in astro-big-doc

The repository provides two implementations for handling image directives, each suited to different performance and flexibility needs.

ImageDirective (Standard Implementation)

Located at src/components/markdown/directive/ImageDirective.astro, this component renders a standard HTML <img> tag. It processes three key attributes: center, width, and height. This is the lightweight option when you need basic styling without build-time optimization.

OptimizedImageDirective (Performance-Optimized)

Found in src/components/markdown/directive/OptimizedImageDirective.astro, this advanced implementation leverages Astro's native <Image> component combined with the sharp library. It reads source file metadata to compute missing dimensions automatically, preserving aspect ratios while generating responsive srcset attributes and modern formats like WebP.

Implementing Centering in Custom Markdown Image Directives

Centering is handled through a boolean flag rather than CSS classes in Markdown. When ImageDirective detects the center attribute in the node, it appends the center class to the element:

let add_class = "";
if (Object.hasOwn(node.attributes, "center")) {
  add_class = "center";
}

The component's scoped <style> block defines the centering behavior:

.center {
  display: block;
  margin-left: auto;
  margin-right: auto;
}

This approach ensures images center horizontally within their container regardless of the parent layout.

Controlling Dimensions with Width and Height Attributes

Both directive implementations support explicit dimension control through width and height attributes, though they handle them differently.

Standard Directive Dimension Handling

ImageDirective applies dimensions as inline styles directly to the <img> tag:

let style = "";
if (node.attributes.width) {
  style += `width:${node.attributes.width}px;`;
}
if (node.attributes.height) {
  style += `height:${node.attributes.height}px;`;
}

Optimized Directive Dimension Handling

OptimizedImageDirective uses sharp to read the image's intrinsic dimensions when only one dimension is provided. Lines 28-38 of the component calculate the missing value to maintain the aspect ratio, then pass both dimensions to Astro's <Image> component. This prevents layout shift while allowing flexible sizing.

Practical Examples

Use these patterns in your Markdown files to control image presentation:

Basic image without styling:

:::image src="/assets/example.png" alt="Sample image":::

Centered image:

:::image src="/assets/example.png" alt="Centered image" center:::

Fixed dimensions:

:::image src="/assets/example.png" alt="Fixed size" width="300" height="200":::

Centered with specific width:

:::image src="/assets/example.png" alt="Centered, fixed width" width="400" center:::

Switching to optimized rendering:

Edit src/components/markdown/directive/Directive.astro to use OptimizedImageDirective instead of ImageDirective. The same Markdown syntax will then generate responsive, optimized images with automatic format conversion.

Summary

• astro-big-doc provides a directive architecture that extends Markdown with custom components through :::directive syntax.
• Two image implementations exist: ImageDirective for standard <img> tags and OptimizedImageDirective for build-time optimized images using sharp.
• Centering is achieved by adding the center attribute, which applies a CSS class with automatic margins.
• Dimensions are controlled via width and height attributes, with the optimized version calculating missing values to preserve aspect ratios.
• The dispatcher in Directive.astro allows easy switching between implementations without changing Markdown content.

Frequently Asked Questions

How do I center an image using the custom markdown image directive?

Add the center attribute to your directive block. The ImageDirective component detects this attribute and applies the center CSS class, which sets margin-left: auto and margin-right: auto to horizontally center the image within its container.

Can I use both width and height attributes together?

Yes, both ImageDirective and OptimizedImageDirective accept width and height attributes simultaneously. When using the optimized version, if you provide only one dimension, the component uses sharp to read the image metadata and automatically calculates the other dimension to maintain the original aspect ratio.

What is the difference between ImageDirective and OptimizedImageDirective?

ImageDirective renders a basic HTML <img> tag with inline styles for dimensions and CSS classes for centering. OptimizedImageDirective leverages Astro's <Image> component and the sharp library to provide build-time optimization, format conversion, responsive srcset generation, and automatic dimension calculation based on source file metadata.

How do I switch from the standard directive to the optimized version?

Open src/components/markdown/directive/Directive.astro and swap the import statements. Comment out the import for ImageDirective and uncomment the import for OptimizedImageDirective. The dispatcher will then route all :::image directives to the optimized component without requiring any changes to your Markdown content.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}