BuildSitemapDocumentsOptions
@ebitex/content-sdk/sitemap — pure functions, and nothing else.
There is deliberately no route, handler, CLI, or runtime here: serving is hosting, and hosting is the one thing this package cannot supply. A request handler or a static build script is a few lines on top of these.
buildSitemapDocuments is the one place the package needs to know where documents are served: a
single sitemap is self-contained, whereas an index references its shards by URL and cannot be
rendered correctly without knowing the paths they will be served at. Serving them is still yours.
Reach for buildSitemapDocuments by default; under the caps its single document is byte-identical
to buildSitemapXml’s output, and past them it is the difference between a sitemap and a throw.
Extends
Section titled “Extends”Properties
Section titled “Properties”exclude?
Section titled “exclude?”
optionalexclude?: readonlystring[]
Paths to omit. An entry is either an exact path (/search) or a subtree (/internal/*).
Consumer policy about pages that genuinely exist, which is why it lives here rather than in the API: membership — what is published and addressable — is decided server-side, but “we would rather not advertise our search results page” is not a fact about the content.
Inherited from
Section titled “Inherited from”BuildSitemapXmlOptions.exclude
filter?
Section titled “filter?”
optionalfilter?: (node) =>boolean
An escape hatch for anything the exclude path list cannot express. Applied after exclude.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”boolean
Inherited from
Section titled “Inherited from”indexPath?
Section titled “indexPath?”
optionalindexPath?:string
Where the index — or, when everything fits in one file, the single document — is served.
The URL robots.txt should advertise. Defaults to /sitemap.xml.
localeUrl?
Section titled “localeUrl?”
optionallocaleUrl?: (path,locale,node) =>string|undefined
Maps a (path, locale) pair to the URL that locale is served at, enabling hreflang alternates.
Omit it and no xhtml:link element is emitted at all — which is the right default, because
only the consuming router knows whether locales live in a path prefix (/es/about), a subdomain
(es.example.com), a query parameter, or nowhere. A site that does not route locales in URLs has
no alternates to declare, whatever its CMS locale configuration says.
The returned value may be absolute (used as-is) or site-relative (joined to origin).
Under server-side locale addressing this narrows to a decision. A site configured
pathPrefix delivers paths that already carry their prefix, and one configured localeHost
delivers an absolute url on every node and slot — so there is nothing left to compose, and
composing again would prefix twice. Pass localeUrl: (path) => path to opt into alternates;
wherever the server sent a url, that url is emitted and your returned string is not used.
Returning undefined still omits the alternate, exactly as below.
path is the path for that locale — which for a page whose Experience node carries a
localized slug is not the default one. The whole node is passed as well so a decision that is
about the page rather than about one of its addresses (the undefined case below is exactly
that) can key on something stable across locales: node.path or node.nodeId.
Return undefined to say this page has no version in that locale, and its alternate is
omitted. That decision can only be made here: the CMS deliberately does not signal translation
(a localeSlots entry means a path materializes in that slot, which happens for every node
once any node carries a localized slug, and a page is routinely translated while keeping its
slug) — so the consumer is the only party that knows, and this is where it says so. Returning
undefined for the default locale is legal and means the page is listed at whichever locale’s
URL does survive.
Parameters
Section titled “Parameters”string
locale
Section titled “locale”string
Returns
Section titled “Returns”string | undefined
Inherited from
Section titled “Inherited from”BuildSitemapXmlOptions.localeUrl
maxBytes?
Section titled “maxBytes?”
optionalmaxBytes?:number
Lower the per-shard byte cap. Defaults to the protocol’s MAX_SITEMAP_BYTES.
maxUrls?
Section titled “maxUrls?”
optionalmaxUrls?:number
Lower the per-shard URL cap. Defaults to the protocol’s MAX_SITEMAP_URLS.
Shapes the shards only. The index is always held to the protocol’s own limits.
origin
Section titled “origin”origin:
string
The absolute origin every <loc> is built on, e.g. https://example.com.
Required, and deliberately not derived from the response’s own site record even though the API knows the site’s mapped hosts: the canonical origin is a deploy-environment fact, not a content one. A preview deployment serving the same content must not emit production URLs, and a site with several mapped hosts has no defensible automatic choice.
Inherited from
Section titled “Inherited from”shardPath?
Section titled “shardPath?”
optionalshardPath?: (index) =>string
The path of shard n, 1-based. Defaults to /sitemap-1.xml, /sitemap-2.xml, …
May return an absolute URL — used as-is, exactly as localeUrl may — for a consumer serving
shards from a CDN or another host.
A sitemap may only contain URLs at or below its own location, so a shard served at
/sitemaps/a.xml may not list /about. The defaults sit at the root and are always safe;
changing this can break that rule. It is documented rather than enforced because the rule has a
legitimate exemption — a verified-ownership cross-submission, which search engines accept — so
validating it would reject working setups in order to catch a mistake this sentence can name.
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”string
xDefaultLocale?
Section titled “xDefaultLocale?”
optionalxDefaultLocale?:string
The locale x-default points at. Defaults to the response’s own defaultLocale — the
organization’s root locale. Only meaningful alongside localeUrl.
Also names the default locale when the response has none (defaultLocale: null — no locale
tree, or no single root): localeUrl is then asked for the default entry under this name, so a
router that prefixes its default locale gets its own address rather than the raw CMS path, which
would redirect. The entry stays unlabelled — the organization never declared that locale, and a
slot may already carry it.