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:
seo: siteUrl: https://docs.example.com
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:
<?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
- Check the seo reference page for more information and examples.
- Set a custom domain to personalize your URL to reflect your brand.
- Learn more about hosting Static assets in Redocly projects.