Images

Embed images in your Mordoc documentation using markdown syntax.

5 min read

Images

Images enhance your documentation by providing visual context, diagrams, screenshots, and illustrations. Mordoc supports standard markdown image syntax.

Basic Image Syntax

Embed images using markdown notation:

Markdown

![Alt Text](/path/to/image.png)

Example

Markdown

![Architecture Diagram](/images/architecture.png)

Result: The image will be displayed inline in your documentation.

Image Components

Required: Alt Text

Alt text describes the image for accessibility and appears when the image fails to load:

Markdown

![User Dashboard Screenshot](/images/dashboard.png)

The text between [ and ] is the alt text. Always provide descriptive alt text.

Optional: Title

Add a title that appears as a tooltip on hover:

Markdown

![Dashboard](/images/dashboard.png "Main user dashboard interface")

The text in quotes after the URL is the title attribute.

Image Paths

Public Directory Images

Store images in the public/ directory and reference them with absolute paths:

public/
├── images/
│   ├── logo.png
│   ├── screenshot.jpg
│   └── diagram.svg
└── icons/
    └── feature.svg

Reference in markdown:

Markdown

![Logo](/images/logo.png)
![Screenshot](/images/screenshot.jpg)
![Diagram](/images/diagram.svg)
![Icon](/icons/feature.svg)

Path Rules

Start paths with / for absolute paths from site root
Paths are case-sensitive on some platforms
Use web-friendly formats: PNG, JPG, SVG, GIF, WebP

File Location	Markdown Path
`public/images/hero.png`	`/images/hero.png`
`public/icons/check.svg`	`/icons/check.svg`
`public/screenshots/app.jpg`	`/screenshots/app.jpg`

Supported Image Formats

Mordoc supports all standard web image formats:

Format	Extension	Best For	Notes
PNG	`.png`	Screenshots, graphics with transparency	Lossless, larger file size
JPEG	`.jpg`, `.jpeg`	Photos, complex images	Lossy compression, smaller files
SVG	`.svg`	Icons, logos, diagrams	Vector format, scalable
GIF	`.gif`	Simple animations	Limited colors, larger files
WebP	`.webp`	Modern web images	Best compression, not universally supported in older browsers

Format Recommendations

Markdown

<!-- Logos and icons -->
![Logo](/images/logo.svg)

<!-- Screenshots -->
![Application Screenshot](/images/app-screenshot.png)

<!-- Photos -->
![Team Photo](/images/team.jpg)

<!-- Diagrams -->
![Architecture Diagram](/images/architecture.svg)

Image Sizing

Images display at their natural size by default. While markdown doesn't support size attributes, you can use HTML for more control.

Using HTML for Size Control

HTML

<img src="/images/diagram.png" alt="Diagram" width="600" />
<img src="/images/icon.svg" alt="Icon" width="48" height="48" />

Responsive Images

Images are automatically responsive and scale to fit their container. For best results:

Use high-resolution images (2x size for retina displays)
Optimize images before adding to documentation
Keep file sizes reasonable for fast loading

Image Optimization

Optimize images before adding them to your documentation to improve page load times. Use tools like ImageOptim, TinyPNG, or SVGO.

External Images

Link to images hosted externally:

Markdown

![Example](https://example.com/image.png)

External images depend on the external server's availability. For critical documentation images, host them in your public/ directory.

Image Alignment

By default, images are left-aligned. Use HTML for custom alignment:

Center Alignment

HTML

<div style="text-align: center;">
  <img src="/images/diagram.png" alt="Centered Diagram" />
</div>

Float Right

HTML

<img src="/images/icon.png" alt="Icon" style="float: right; margin: 0 0 1rem 1rem;" />

Image with Caption

Create image captions using HTML:

HTML

<figure>
  <img src="/images/architecture.png" alt="System Architecture" />
  <figcaption>Figure 1: System Architecture Overview</figcaption>
</figure>

Clickable Images

Make images clickable by wrapping them in a link:

Markdown

[![Screenshot](/images/small-screenshot.png)](/images/full-screenshot.png)

This creates a thumbnail that opens the full-size image when clicked.

Best Practices

Alt Text Guidelines

Good Alt Text:

Describes the image content: ![User authentication flow diagram](/images/auth-flow.png)
Is concise but descriptive: ![Dashboard showing analytics and metrics](/images/dashboard.png)
Omits unnecessary phrases: ![Mobile app interface](/images/mobile.png) (not "Image of mobile app interface")

Poor Alt Text:

Too vague: ![Image](/images/screenshot.png)
Too long: ![This is a screenshot showing the main dashboard interface with a sidebar on the left containing navigation menu items...](/images/dashboard.png)
Uses "image of": ![Image of dashboard](/images/dashboard.png)

Accessibility

Always Provide Alt Text: Screen readers rely on alt text
Describe Content, Not Appearance: Focus on what the image conveys
Decorative Images: Use empty alt text ![]() for purely decorative images
Complex Images: Provide detailed descriptions in surrounding text

File Organization

public/
├── images/
│   ├── screenshots/
│   │   ├── dashboard.png
│   │   └── settings.png
│   ├── diagrams/
│   │   ├── architecture.svg
│   │   └── workflow.svg
│   └── photos/
│       └── team.jpg
└── icons/
    ├── feature-1.svg
    └── feature-2.svg

Organize images in logical subdirectories for easier maintenance.

Performance

Optimize File Size: Compress images without visible quality loss
Use Appropriate Format: SVG for icons, PNG for screenshots, JPEG for photos
Avoid Huge Dimensions: Scale images to maximum display size
Consider Lazy Loading: Large pages benefit from lazy-loaded images

Naming Conventions

Use descriptive names: user-dashboard.png (not img1.png)
Use lowercase and hyphens: api-flow-diagram.svg
Include version if needed: architecture-v2.svg
Be consistent across your project

Common Use Cases

Screenshots

Markdown

## Installation Complete

After installation, you'll see the success screen:

![Installation success screen showing completion message](/images/install-complete.png)

Diagrams

Markdown

## System Architecture

The system consists of three main components:

![Architecture diagram showing frontend, API, and database layers](/images/architecture.svg)

Icons with Text

Markdown

{% cardGrid cols="3" %}
{% card title="Fast" icon="/icons/speed.svg" %}
Optimized for performance
{% /card %}

{% card title="Secure" icon="/icons/lock.svg" %}
Built with security in mind
{% /card %}

{% card title="Scalable" icon="/icons/scale.svg" %}
Grows with your needs
{% /card %}
{% /cardGrid %}

Before and After

Markdown

## Theme Update

**Before:**
![Old theme interface](/images/theme-before.png)

**After:**
![New theme interface](/images/theme-after.png)

Troubleshooting

Image Not Displaying

Verify file exists in public/ directory
Check path starts with /
Ensure filename matches exactly (case-sensitive)
Check file format is supported
Rebuild the site: npm run build

Image Too Large/Small

Use HTML <img> tag with width/height attributes
Resize the original image file
Check image dimensions in image editor

Broken External Images

Verify external URL is accessible
Consider hosting critical images locally
Check for HTTPS/HTTP protocol issues

Always test images after building your site. Some path issues only appear in production builds.

Examples

Complete Documentation Section

Markdown

# User Interface Guide

## Dashboard Overview

The main dashboard provides quick access to key features:

![Main dashboard with sidebar navigation and content area](/images/dashboard-overview.png "User Dashboard")

### Key Components

1. **Navigation Sidebar**: Access different sections
   ![Sidebar navigation menu](/images/sidebar.png)

2. **Content Area**: View and manage your content
   ![Content management interface](/images/content-area.png)

3. **User Profile**: Manage account settings
   ![User profile dropdown menu](/images/profile-menu.png)

Next Steps

Lists - Create ordered and unordered lists
Tables - Display structured data
Code Blocks - Add syntax-highlighted code