Figures and Captions

Semantic HTML figures with images and captions for better accessibility

Figures and Captions

The figure extension creates semantic HTML5 <figure> and <figcaption> elements, perfect for images that need explanatory captions in documentation, tutorials, and educational content.

Basic Syntax

Use :::figure with an image and caption:

Architecture diagram
This diagram shows the complete system architecture with all microservices and their interactions.

With Custom Labels

Add numbered or titled labels to your figures:

System architecture
Figure 1: System Overview The complete system architecture showing the API gateway, microservices, and database layers.

Common Use Cases

1. Technical Documentation

Document system architecture and diagrams:

Component diagram
Figure 1: Component Architecture The application follows a modular architecture with separate frontend, backend, and database layers.

2. Tutorial Screenshots

Explain user interface elements:

Dashboard screenshot
Step 2: Dashboard View After logging in, you'll see the main dashboard with navigation on the left and content area on the right.

3. Before/After Comparisons

Show the result of changes:

New design
Figure 2: Redesigned Interface The redesigned interface features a cleaner layout with improved visual hierarchy and better spacing.

4. Data Visualizations

Present charts and graphs:

Performance chart
Chart 1: Performance Metrics Response times improved by 60% after implementing caching and code optimization.

5. Code Output Examples

Show visual results:

CSS Grid layout
Figure 3: Rendered Output The CSS Grid layout creates a responsive two-column design that adapts to screen size.

6. Workflow Diagrams

Illustrate processes:

CI/CD pipeline
Workflow: Deployment Pipeline The automated deployment pipeline runs tests, builds the application, and deploys to production.

Markdown in Captions

Captions support full markdown formatting:

Example
This shows the old design with outdated styling. See the legacy-styles.css file for details, or visit the design history page.

Multiline Captions

Captions can span multiple lines for detailed explanations:

Database ERD
Figure 4: Database Schema The database schema includes user authentication tables, content management tables, and analytics tracking. Each table is normalized to third normal form (3NF) to prevent data redundancy. Foreign key relationships maintain referential integrity across the system.

Without Captions

You can use figures without captions when the image is self-explanatory:

Self-explanatory diagram

Label-Only Figures

Use labels without additional caption text:

Simple diagram
Diagram A

Features

Semantic HTML

The extension generates proper HTML5 structure:

<figure class="markdown-figure">
  <img src="image.jpg" alt="Description" loading="lazy">
  <figcaption>
    <strong class="figure-label">Figure 1</strong>
    <span class="figure-caption-text">Caption text here.</span>
  </figcaption>
</figure>
HTML

Performance Optimization

All images include loading="lazy" for better performance:

  • Reduces initial page load time
  • Images load only when needed
  • Improves Core Web Vitals scores

Accessibility

Figures are accessible by default:

  • Semantic <figure> element for screen readers
  • Alt text on images for visually impaired users
  • Captions provide context for all users
  • Proper heading hierarchy with labels

Integration with Other Components

In Steps

Use figures in step-by-step tutorials:

steps

Step 1: Open the Dashboard

Navigate to the main dashboard:

Dashboard menu
Figure 1: Dashboard Location Click on "Dashboard" in the main navigation menu.

Step 2: Configure Settings

Access the settings panel:

Settings view
Figure 2: Settings Panel The settings panel appears on the right side of the screen.

In Cards

Include figures in card layouts:

Architecture Overview

Our system uses a microservices architecture:

Architecture
System Architecture Three main microservices handle authentication, data processing, and API gateway functions.

In Asides

Add figures to callout boxes:

In Tabs

Show different views:

Desktop screenshot
Desktop Layout The desktop view shows all navigation elements and a three-column layout.
Mobile screenshot
Mobile Layout The mobile view uses a hamburger menu and single-column layout.

Best Practices

Use Descriptive Alt Text

✅ Good:

![Database schema showing user, post, and comment tables with relationships](schema.png)
Markdown

❌ Poor:

![diagram](image.png)
Markdown

Write Clear Captions

✅ Good:

API diagram
Figure 1: API Response Flow The client sends a request to the API gateway, which routes it to the appropriate microservice. The response follows the reverse path back to the client.

❌ Vague:

API
This is how the API works.

Number Figures Sequentially

When using multiple figures, number them in order:

Overview
Figure 1: Overview System overview showing main components.
Detail view
Figure 2: Detail Detailed view of the authentication service.

Keep Labels Consistent

Choose a labeling scheme and stick to it:

✅ Consistent:

  • Figure 1: Component A
  • Figure 2: Component B
  • Figure 3: Component C

❌ Inconsistent:

  • Fig 1: Component A
  • Figure 2: Component B
  • Diagram 3: Component C

Reference Figures in Text

Refer to figures in surrounding text:

As shown in the diagram below, the system consists of three main layers.

Three-tier architecture
Figure 1: System Layers The presentation, business logic, and data layers are clearly separated.

The presentation layer (Figure 1) handles all user interactions.

Styling Tips

The .markdown-figure class allows for custom styling:

.markdown-figure {
  margin: 2rem auto;
  max-width: 800px;
  text-align: center;
}

.markdown-figure img {
  width: 100%;
  height: auto;
  border-radius: 8px;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
}

.markdown-figure figcaption {
  margin-top: 1rem;
  font-size: 0.9rem;
  color: #666;
  text-align: left;
}

.figure-label {
  color: #2563eb;
  font-weight: 600;
}
CSS

Comparison with Plain Images

Plain Markdown Image

![Architecture](diagram.png)
*Figure 1: System architecture showing all components*
Markdown

Problems:

  • Caption is just italic text (not semantic)
  • No connection between image and caption
  • Screen readers don't know they're related
  • Can't be styled as a unit

Figure Extension

:::figure[Figure 1: System Architecture]
![Architecture](diagram.png)
Complete system architecture showing all components and their relationships.
:::
Markdown

Benefits:

  • Semantic HTML structure
  • Image and caption are grouped
  • Screen readers announce as figure
  • Easy to style consistently
  • Better accessibility

Error Handling

If you forget to include an image:

Error: Figure requires an image.

An error message will display: "Error: Figure requires an image."

Real-World Examples

Documentation Example

API Reference:

Auth flow diagram
Figure 1: Authentication Flow The OAuth 2.0 authentication flow begins with the client requesting authorization. The authorization server validates credentials and issues an access token. The client uses this token for subsequent API requests.

Tutorial Example

Building a Layout:

Completed layout
Step 3 Result After applying CSS Grid, the layout displays three equal-width columns on desktop screens. On mobile devices, it automatically switches to a single-column layout for better readability.

Research/Technical Writing

Experimental Results:

Performance chart
Figure 3: Performance Comparison Load times decreased by 65% after implementing lazy loading and code splitting. The graph shows response times before (blue) and after (green) optimization.

Browser Compatibility

The <figure> and <figcaption> elements are supported in all modern browsers:

  • Chrome/Edge (all versions)
  • Firefox (all versions)
  • Safari (all versions)
  • Mobile browsers

The loading="lazy" attribute is supported in:

  • Chrome 77+
  • Firefox 75+
  • Safari 15.4+
  • Edge 79+

Older browsers simply ignore the lazy loading attribute and load images normally.

Syntax Reference

:::figure
![Alt text](image.jpg)
Caption text here.
:::
Markdown

With label:

:::figure[Figure 1: Title]
![Alt text](image.jpg)
Caption with **markdown** formatting.
:::
Markdown

Parameters:

  • label (optional) - Text for the figure label (e.g., "Figure 1", "Diagram A")
  • First line with image - Standard markdown image syntax
  • Following lines - Caption text (supports markdown)
  • Image Compare - For before/after comparisons with slider
  • Cards - For containing figures in styled boxes
  • Tabs - For showing different figure variations
  • Details - For collapsible figures
Back to Markdown Features