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. There are two ways to add a sitemap to your project:

  • Configure 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>

Add a custom sitemap

Add a custom sitemap by placing a sitemap.xml file into the /static folder in the root of your project. Redocly serves the sitemap but doesn't validate the structure, so you should validate your sitemap before adding the file.

your-awesome-project
├── static
│   └── sitemap.xml
├── guides
├── redocly.yaml
└── ...

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 priority and changefreq. 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