Skip to main content

Developing in Cascade how to

Creating a sitemap

Worked example

This walks through one way to build a sitemap rather than documenting a Cascade CMS feature. Adapt it to your own site structure.

Why create a sitemap?

A sitemap helps search engines crawl your site more efficiently. It provides a structured list of pages, improving SEO and ensuring updates are picked up faster. Sitemaps are especially important for large sites or those with complex folder structures.

Each site in Cascade should typically have its own sitemap. If you manage multiple sites, you can also create a sitemap index to link to each individual sitemap, following the standard XML Sitemap Index protocol.

Setting up the sitemap page

To create a sitemap, you first need a dedicated page with:

  • A Content Type designed for a sitemap.

  • A Template with a single region (usually called something like DEFAULT or XML).

  • A Configuration Set ensuring the page publishes with a .xml extension.

Key setup notes:

  • Root Placement: The sitemap page should live at the root of the site (/sitemap.xml or /index.xml depending on preference).

  • Template Region: The format or block you attach will generate the entire XML output within this region.

Tip: Disable WYSIWYG fields in your sitemap content type; the output should be fully controlled by the attached Format or Block.

Methods for building the sitemap

A sitemap helps search engines crawl your site more efficiently. It provides a structured list of pages, improving SEO and ensuring updates are picked up faster. Sitemaps are especially important for large sites or those with complex folder structures.

Each site in Cascade should typically have its own sitemap. If you manage multiple sites, you can also create a sitemap index to link to each individual sitemap, following the standard XML Sitemap Index protocol.

There are a few common methods to generate sitemap content in Cascade CMS. Each has tradeoffs between speed, flexibility, and scalability.

1. Using an Index Block

Overview:
You attach an Index Block to the region, with a simple XML Format to loop through and output links to your pages.

Pros:

  • Very easy to set up.

  • Good if you need to respect folder-level Index/Publish settings.

Cons:

  • Slow on large sites.

  • Index Blocks retrieve assets recursively at render time, so performance degrades with thousands of pages.

XML 
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">

2. Using Cascade API Queries ( $_.query())

Overview:
Write a Velocity Format that queries pages via the internal Cascade API.

Pros:

  • Faster than Index Blocks.

  • Up to 2,000 assets per query.

  • Better control over fields to preload (performance boost).

Cons:

  • Only returns assets individually set to Index/Publish.

  • Ignores folder-level publish settings unless you filter manually.

  • Cannot recurse folder structures like Index Blocks.

Velocity 
#set ($pages = $_.query().byContentType("Default-Page").indexableOnly(true).preloadDynamicMetadata().maxResults(-1).execute())
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
#foreach ($page in $pages)
 <url>
 <loc>https://yoursite.com${page.path}.html</loc>
 </url>
#end
</urlset>

3. Using Query Directives ( #queryexecute)

Overview:
A newer, more scalable approach that uses directives instead of .execute(). Supports up to 100,000 results.

Pros:

  • Massive scalability (10x higher limits than .execute()).

  • Still relatively fast compared to Index Blocks.

Cons:

  • Same limitations as Cascade API: doesn't "see" folder-level index/publish settings properly.

  • Slightly more complex to maintain.

Example:

Velocity 
#set ($query = $_.query().byContentType("Default-Page").indexableOnly(true).preloadDynamicMetadata())

Configuration tips for sitemap pages

When setting up the sitemap's Configuration Set, make sure to:

  • Set the Output Extension to .xml.

  • Enable "Include XML Declaration in Published Files".

Enabling the XML Declaration ensures that your sitemap starts with:

<?xml version="1.0" encoding="UTF-8"?>
 

This line is required for strict XML parsers and helps search engines properly validate your sitemap files.

How to enable it:

  • Edit the Configuration Set attached to your sitemap page.

  • Under Publishing Settings, check Include XML Declaration in Published Files.

  • Save and republish the sitemap.

Final notes

  • Always validate your sitemap using a Sitemap Validator before submitting to search engines.

  • Consider setting a regular publish schedule for sitemap pages, especially for dynamic sites where URLs change often.

  • Keep sitemap sizes below 50,000 URLs per file (Google’s limit) — although Cascade query size limits will usually keep you well below that.