Image Usage Examples

This document outlines our best practices for image handling using Docusaurus.

Image Examples

See the Step-By-Step Examples page for examples of using images in a step-by-step fashion.

Image Storage

Store images in an images/ subdirectory next to your markdown files. Each directory has its own images directory:

docs/
  some-doc-directory/
    your-doc-page1.md
    your-doc-page2.md
    images/
      step-1-overview.png
      step-2-settings.png
      step-3-confirmation.png

note

Global images (images that are used on the landing page or over multiple pages) should be put in the ./static/img directory

Image Naming Best Practices

• Descriptive names: step-1-login-screen.png instead of image1.png
• Sequential numbering: Use consistent numbering for multi-step processes

Image Accessibility Best Practices:

• Alt text: Brief description of what the image shows
• Figure captions: More detailed explanation of the image content

Image Markup

You should use Markdown syntax for your images, however, there is no way to specify sizing in Markdown so the fallback for those cases is to use HTML (the <img> tag ). There may also be cases where you need to use design elements that Markdown cannot handle.

Basic Image

![Alt text description](./images/number1.png)

Image with Caption

![Alt text for screen readers](./images/number2.png)

*Figure 1: Caption that provides additional context about the image*

Image with Title Attribute

![Alt text](./images/number3.png "Hover tooltip text")

HTML for Advanced Control

<!-- Set specific width -->
<img 
  src={require('./images/number4.png').default} 
  alt="Detailed description" 
  width="600" 
/>

<!-- Set width and height -->
<img 
  src={require('./images/number5.png').default} 
  alt="Detailed description" 
  width="800" 
  height="400"
/>

<!-- Use percentage width -->
<img 
  src={require('./images/number6.png').default} 
  alt="Detailed description" 
  width="50%" 
/>

<!-- Advanced styling with CSS -->
<img 
  src={require('./images/number7.png').default}
  alt="Detailed description" 
  style={{
    width: '600px',
    maxWidth: '100%',
    height: 'auto',
    border: '1px solid #ccc', 
    borderRadius: '8px',
    boxShadow: '0 2px 8px rgba(0,0,0,0.1)'
  }}
/>

Image Sizing

Method 1: HTML img tag (Recommended)

<!-- Small image (300px) -->
<img src={require('./images/number1.png').default} alt="Application icon" width="300" />

<!-- Medium image (600px) -->
<img src={require('./images/number2.png').default} alt="Dashboard view" width="600" />

<!-- Large image (900px) -->
<img src={require('./images/number3.png').default} alt="Full interface" width="900" />

<!-- Responsive image (50% of container) -->
<img src={require('./images/number4.png').default} alt="Process diagram" width="50%" />

<!-- Image with max-width constraint -->
<img 
  src={require('./images/number5.png').default}
  alt="Complex interface" 
  style={{width: '800px', maxWidth: '100%'}}
/>

Method 2: CSS Classes (Custom Styling)

<!-- Define custom CSS classes in your component or global CSS -->
<img src={require('./images/example.png').default} alt="Example" className="image-small" />
<img src={require('./images/example.png').default} alt="Example" className="image-medium" />
<img src={require('./images/example.png').default} alt="Example" className="image-large" />

src/css/custom.css

.image-small {
  width: 300px;
  max-width: 100%;
  height: auto;
}

.image-medium {
  width: 600px;
  max-width: 100%;
  height: auto;
}

.image-large {
  width: 900px;
  max-width: 100%;
  height: auto;
}

Method 3: Inline Styles (Flexible)

<!-- Specific pixel width -->
<img 
  src={require('./images/example.png').default}
  alt="Example image" 
  style={{width: '400px', height: 'auto'}} 
/>

<!-- Percentage-based sizing -->
<img 
  src={require('./images/example.png').default}
  alt="Example image" 
  style={{width: '75%', height: 'auto'}} 
/>

<!-- Responsive with constraints -->
<img 
  src={require('./images/example.png').default}
  alt="Example image" 
  style={{
    width: '100%', 
    maxWidth: '500px', 
    height: 'auto'
  }} 
/>