Last updated

Add a sitemap

A sitemap is a resource that lists all the pages in your website to help search engines and other automation tools to identify all the pages available.

You can add a sitemap to your project in one of the following two ways:

  • Configure your project to generate a sitemap (supported by all Redocly products).
  • Create a custom sitemap and add it as a static asset.

Generate a sitemap

When the siteUrl is set, Redocly will generate and host a sitemap file for your project at build time. To enable the sitemap feature, add your site's domain to siteUrl in the seo section of your redocly.yaml configuration file, as shown in the following example:

redocly.yaml
seo:
  siteUrl: https://docs.example.com
No protected content

The generated sitemap does not include any pages protected by role based access controls or pages listed in the ignore configuration.

The data is formatted to standard search engine expectations, using the <loc> tag. A snippet is shown below:

docs.example.com/sitemap.xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:news="http://www.google.com/schemas/sitemap-news/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1" xmlns:video="http://www.google.com/schemas/sitemap-video/1.1">
  <url>
    <loc>https://docs.example.com/</loc>
  </url>
  <url>
    <loc>https://docs.example.com/reference/</loc>
  </url>
</urlset>

Default priority

Redocly sets the optional priority property for pages in the generated sitemap.xml file to 0.5, unless the pages are non-default versioned content. For pages that are non-default versioned content pages, the optional priority property is set to 0.3 in the generated sitemap.xml file. This distinction tells search engines the default version of content is more important than the non-default versions.

Add a custom sitemap

Add a custom sitemap by placing a sitemap.xml file into the /static folder in the root of your project, as in the following example file tree:

Example file tree with sitemap.xml file
your-awesome-project
├── static
│   └── sitemap.xml
├── guides
├── redocly.yaml
└── ...
Validate your sitemap

Redocly serves the sitemap but doesn't validate the structure, so you should validate your sitemap before adding the file.

View the sitemap

After enabling the sitemap or adding it as a static file, view your project's sitemap by navigating to https://docs.example.com/sitemap.xml in a preview build or in production. The sitemap is not visible from a local preview after making the change.

When viewing the sitemap, some browsers show the raw XML while others render it in a nice structure. However, this manual review step is just for verification. Search engines only care about the data.

Search engine considerations

More advanced sitemap configuration is possible using additional properties, such as changefreq and lastmod. However, the sitemap generated by Redocly does not include these. You'll need to add a custom sitemap to your project with those properties.

For best results with search engines, your project should also include a robots.txt file (see Add a robots.txt file) that provides an absolute URL to the hosted sitemap.

Resources

 
Next page