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

> Easily create custom Markdown image directives in Astro Extend Markdown with :::image blocks supporting center width and height attributes for precise layout control with astro-big-doc

- Repository: [Micro Web Stacks/astro-big-doc](https://github.com/microwebstacks/astro-big-doc)
- Tags: how-to-guide
- Published: 2026-03-07

---

**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.

```astro
<!-- 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:

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

```

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

```css
.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:

```ts
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:**

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

```

**Centered image:**

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

```

**Fixed dimensions:**

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

```

**Centered with specific width:**

```markdown
:::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.