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 Markdown and MDX files effectively.

1. Using Images in Markdown

Grass, Tree, Sky

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

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.

Adding Titles to Images

Grass, Tree, Sky

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.

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_

trees, grass, and sky

trees, grass, and sky

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.

Images in Next.js Public Folder

In Next.js, you can place your images in the public folder, which allows you to reference them directly from the root of the application. For example:

markdown
![Grass, Tree, Sky](/images/posts/how-to-use-images/grass-tree-sky.jpg)

The image above exists in the public folder, which is not processed by webpack. This makes it ideal for static assets like images.

2. Using Images in MDX Files

MDX (Markdown with JSX) is a powerful way to use React components inside markdown files. While the basic Markdown image syntax works in MDX, you can take advantage of React components for greater flexibility.

Basic Markdown Image in MDX

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

Using Next.js Image Component in MDX

MDX allows you to use the Next.js Image component to optimize and handle responsive images:

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

You can create a custom image component to handle additional functionality like captions and titles:

mdx
import Image from "@/components/mdx/image";

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

If you're using MDXBlog, this custom <Image /> component should already be available via the mdx-components.tsx file, so you don't need to import it manually.

Handling Images Responsively in MDX

When using the next/image component or a custom component, you can manage responsiveness by setting the layout to 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.

3. Best Practices for Using Images

  • Optimize Images: Use tools like ImageOptim or modern formats like WebP to reduce file sizes and improve loading times.
  • Always Include Alt Text: Descriptive alt text improves accessibility and SEO.
  • Ensure Responsiveness: Test your images on different devices to ensure they display properly.
  • Organize Your Images: Keep your images in a dedicated folder (e.g., /public/images/) for easy reference.
  • Use Next.js Features: Take advantage of the Next.js Image component for built-in optimization and lazy loading.

Conclusion

Start with basic Markdown syntax, and for more advanced use cases, leverage the power of MDX and React components like Next.js's Image. Following best practices for image optimization, accessibility, and responsiveness ensures your content is both user-friendly and visually appealing.

Related Posts