Skip to main content

Create image sitemap file for Docusaurus

· 4 min read
Serhii Hrekov
Serhii Hrekov
software engineer, creator, artist, programmer, projects founder

Docusaurus doesn't have a built-in feature to create a separate image sitemap. The @docusaurus/plugin-sitemap only handles generating a sitemap for your pages and documentation, not for media like images.

Since the plugin doesn't have a specific option for image sitemaps, the recommended approach is to manually create an XML file that follows the image sitemap protocol and place it in the static directory of your Docusaurus project.

Create the Image Sitemap File​

Create a file named image-sitemap.xml (or similar) in the static/ directory of your Docusaurus project. This directory is used for static assets that are copied directly to the final build output.

The file should adhere to the Google image sitemap guidelines. Each <url> entry should contain at least one <image:image> tag.

Here is an example structure:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">

  <url>
    <loc>https://hrekov.com/about</loc>
    <image:image>
      <image:loc>https://hrekov.com/img/serhii-hrekov-profile-photo.jpg</image:loc>
      <image:caption>Professional photo of Serhii Hrekov - software engineer</image:caption>
    </image:image>
  </url>


</urlset>

Key fields:

  • <loc>: The URL of the page where the image is located.
  • <image:loc>: The URL of the image itself.
  • <image:caption>: A caption for the image. This can be used to describe the image.
  • <image:title>: The title of the image.

Submit the Sitemap​

After you build your Docusaurus site, the image-sitemap.xml file will be available at https://your-website.com/image-sitemap.xml. You must submit this sitemap to search engines like Google via Google Search Console to ensure your images are discovered and indexed.

You have two main options for submission:

  1. Direct Submission: Go to the Sitemaps section in Google Search Console and submit the URL for your new image sitemap (/image-sitemap.xml).
  2. Sitemap Index File: While Docusaurus doesn't generate a sitemap index file by default, you could manually create one. This file, which acts as a master list of all your sitemaps, would reference both your main sitemap.xml and your new image-sitemap.xml. This is the most efficient way to manage multiple sitemaps.

Why this Approach?​

Since Docusaurus's sitemap plugin only focuses on HTML pages and doesn't provide options to crawl for images, a manual or scripted approach is necessary. Placing the file in the static folder is the correct Docusaurus practice for including custom, non-dynamic assets in your build.