MDXBlog

2024-08-27 Web Development

How to Use Images in MDX or Markdown Files

By O Wolfson

Whether you’re writing a blog post, documentation, or any other content, knowing how to properly include and manage images is crucial. In this article, we'll explore how to use images in MDX and Markdown files effectively.

1. Basic Image Syntax in Markdown

In Markdown, the most straightforward way to include an image is by using the following syntax:

markdown
![Alt text](path/to/image.jpg)
  • Alt text: Describes the image and is displayed if the image cannot be loaded.
  • Path to the image: Can be a relative path (e.g., ./images/pic.jpg) or an absolute URL (e.g., https://example.com/image.jpg).

Grass, Tree, Sky

The image above happens to exist in the local public folder in this Next.js project. In Next.js, the public folder is a special folder that is not processed by webpack. Files inside the public folder can be referenced from the root of the application similar to how you would reference files in a static site. /images/posts/how-to-use-images/grass-tree-sky.jpg

trees, grass, and sky
trees, grass, and sky

Above is our custom image component. It's a simple component, based on Next's Image component, that takes an image source and a caption as props and renders the image with the caption below it.

jsx
<Image
  alt="trees, grass, and sky"
  src="/images/posts/how-to-use-images/grass-tree-sky.jpg"
  caption="trees, grass, and sky"
/>

Example:

markdown
![A beautiful sunset](/images/sunset.jpg)

This will display an image with the alternative text "A beautiful sunset" if the image fails to load.

2. Adding Titles to Images

You can also add a title to your images, which appears as a tooltip when you hover over the image:

markdown
![Alt text](path/to/image.jpg "Title text")

Example:

markdown
![A beautiful sunset](/images/sunset.jpg "Sunset in the mountains")

This syntax adds a tooltip that appears when users hover over the image.

3. Using Images in MDX Files

MDX (Markdown with JSX) is a powerful way to use React components inside markdown files. You can use the basic markdown image syntax in MDX as well, but MDX allows you to go further by using React components like Next.js's Image component.

Basic Markdown Image in MDX:

mdx
![A beautiful sunset](/images/sunset.jpg)

Using Next.js Image Component in MDX:

mdx
import Image from "next/image";

<Image
  src="/images/sunset.jpg"
  alt="A beautiful sunset"
  width={700}
  height={400}
/>

This method is particularly useful if you need to optimize images, handle responsive images, or include advanced functionality provided by the Image component.

Custom Image Component in MDX

If you need more control or customization, you can create a custom image component and use it within your MDX files:

tsx
// components/CustomImage.tsx
import Image from "next/image";

const CustomImage = ({ src, alt, width, height }) => (
  <div style={{ border: "2px solid #000", padding: "10px" }}>
    <Image src={src} alt={alt} width={width} height={height} />
  </div>
);

export default CustomImage;

Then, import and use it in your MDX file:

mdx
import CustomImage from "./components/CustomImage";

<CustomImage
  src="/images/sunset.jpg"
  alt="A beautiful sunset"
  width={700}
  height={400}
/>

4. Using Images with External URLs

You can also use images hosted on external sites by providing the full URL:

markdown
![Alt text](https://example.com/image.jpg)

Example:

markdown
![MDX Logo](https://www.mdxblog.io/logos/mdx-logo.png)

This method is handy when you want to include images that are not part of your local project or when you want to link to external resources.

5. Handling Images Responsively

When using the next/image component or similar tools, you can manage image responsiveness by providing different sizes or allowing the layout to be responsive:

mdx
<Image
  src="/images/sunset.jpg"
  alt="A beautiful sunset"
  layout="responsive"
  width={700}
  height={400}
/>

This ensures that your images scale correctly on different screen sizes, improving user experience across devices.

6. Including Captions for Images

Captions can be added directly below the image in Markdown:

markdown
![A beautiful sunset](/images/sunset.jpg)

_Sunset in the mountains_

In MDX, you can customize how captions are displayed by wrapping the image and caption in a custom component:

mdx
<div style={{ textAlign: "center" }}>
  <Image
    src="/images/sunset.jpg"
    alt="A beautiful sunset"
    layout="responsive"
    width={700}
    height={400}
  />
  <p>
    <em>Sunset in the mountains</em>
  </p>
</div>

7. Best Practices for Using Images

  • Optimize Images: Ensure that your images are optimized for web use to reduce loading times.
  • Use Alt Text: Always include alt text to improve accessibility and SEO.
  • Responsive Design: Make sure your images are responsive to provide a better experience on all devices.
  • Use Appropriate Formats: Use modern image formats like WebP for better performance, when supported.

Conclusion

Including images in your MDX or Markdown files enhances your content, making it more engaging and informative. Whether you're using the basic markdown syntax or leveraging the power of React components in MDX, you have many options for integrating images effectively. Remember to follow best practices for image optimization, accessibility, and responsiveness to ensure that your content is both user-friendly and visually appealing.

Related Posts