Customize site-wide files

Cactal’s singleton source files apply behavior across a website. Use not_found for unmatched paths and the four custom HTML slots for third-party tags that must appear at an exact document position.

Site-wide settings at a glance

Setting	Where it lives	Lease	Publish for production
Site metadata and redirects	`website_config` source	Required	Required
Global CSS and Tailwind	`global_css` source	Required	Required
Custom 404 page	`not_found` source	Required	Required
Custom head/body HTML	Four custom-code source singletons	Required	Required
Website name and slug	Website resource	Not required	No
Favicon	Website favicon setting	Not required	No
Custom and primary domains	Domain resources	Not required	No, but a site must be published to serve

Source-backed settings follow head and published versions. Current-resource settings such as the favicon apply immediately and are not restored by source rollback.

Create a custom not-found page

The not_found singleton is a page module with the reserved route literal not_found:

not_found

import { definePage } from '@website'

export default definePage({
	route: 'not_found',
	metadata: {
		title: 'Page not found',
		description: 'The requested page could not be found.',
		robots: { index: false, follow: false }
	},
	render: ({ path }) => (
		<main className="mx-auto max-w-2xl px-6 py-24 text-center">
			<p className="text-sm font-medium uppercase tracking-widest">404</p>
			<h1 className="mt-4 text-4xl font-semibold">Page not found</h1>
			<p className="mt-4 text-slate-600">
				No page exists at <code>{path}</code>.
			</p>
			<a className="mt-8 inline-block underline" href="/">
				Return home
			</a>
		</main>
	)
})

The file identity is { "type": "not_found" }; it has no name. The special route is not a public URL pattern and must be exactly not_found, without a leading slash. When no page or redirect matches, Cactal renders this page with the originally requested path, the request’s query map, and an empty route-parameter map. The HTTP response remains 404, so crawlers and clients receive the correct status. Without a not_found file, Cactal returns its standard platform 404 response.

Use CMS data on the 404 page

The not-found page supports the same queries, metadata, and render props as other pages. For example, it can retrieve published navigation links:

not_found

import { definePage } from '@website'

export default definePage({
	route: 'not_found',
	queries: ({ cms }) => ({
		links: cms.navigation_links.list({ limit: 6 })
	}),
	metadata: {
		title: 'Page not found',
		robots: { index: false }
	},
	render: ({ data, path }) => (
		<main>
			<h1>Nothing at {path}</h1>
			<nav>
				{data.links.items.map(link => (
					<a key={link.id} href={link.fields.url}>
						{link.fields.label}
					</a>
				))}
			</nav>
		</main>
	)
})

Only published CMS items are available, including on the draft host. A failing CMS query can prevent the 404 page from rendering, so keep its dependencies small and resilient.

A get query that finds no published item on a regular page falls through to not_found with HTTP 404, so a deleted or unpublished item serves this page instead of an error.

Add custom document HTML

Four singleton types insert raw HTML into every server-rendered page:

File type	Exact position	Typical uses
`custom_head_start`	Immediately after `<head>`, before Cactal metadata and site CSS	Early connection hints, required verification tags, critical third-party setup
`custom_head_end`	After Cactal metadata and the compiled site stylesheet, before `</head>`	Deferred third-party scripts, external stylesheets, additional tags
`custom_body_start`	Immediately after `<body>`, before the React root	Noscript fallbacks, tag-manager body snippets
`custom_body_end`	After the React root and Cactal hydration scripts, before built-in analytics and `</body>`	Widgets and scripts that should run after page hydration

The effective document order is:

<!doctype html>
<html>
  <head>
    <!-- custom_head_start -->
    <!-- Cactal metadata -->
    <style><!-- compiled global_css --></style>
    <!-- custom_head_end -->
  </head>
  <body>
    <!-- custom_body_start -->
    <div id="root"><!-- server-rendered page --></div>
    <!-- Cactal platform, site, and hydration scripts -->
    <!-- custom_body_end -->
    <!-- built-in analytics, when enabled -->
  </body>
</html>

Add a head integration

Set custom head HTML

curl -X PUT 'https://api.cactal.ai/v1/websiteSourceCode/files' \
  -H "Authorization: Bearer $CACTAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "websiteId": "V1StGXR8_Z5jdHi6B-myT",
    "file": { "type": "custom_head_end" },
    "content": "<link rel=\"preconnect\" href=\"https://widget.example.com\">\n<script defer src=\"https://widget.example.com/client.js\"></script>",
    "leaseToken": "exampleLeaseToken00000000000000000000000000"
  }'

Add a tag-manager fallback

Set custom body-start HTML

curl -X PUT 'https://api.cactal.ai/v1/websiteSourceCode/files' \
  -H "Authorization: Bearer $CACTAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "websiteId": "V1StGXR8_Z5jdHi6B-myT",
    "file": { "type": "custom_body_start" },
    "content": "<noscript><iframe src=\"https://tags.example.com/fallback\" height=\"0\" width=\"0\" hidden></iframe></noscript>",
    "leaseToken": "exampleLeaseToken00000000000000000000000000"
  }'

Delete a slot with DELETE /v1/websiteSourceCode/files and the same { websiteId, file, leaseToken } shape.

Raw HTML and security

Custom slot content is inserted without escaping, sanitization, templating, or React processing. It can run scripts, load remote resources, modify the DOM, collect visitor data, or break page markup.

Treat custom HTML as privileged executable code. Paste only code you trust, review every remote hostname, and remove integrations you no longer use. Anyone who can edit full website source can change these slots.

Additional rules:

Slots apply to every rendered page, including the custom 404 page.
Slots cannot vary by route or use CMS/request template values.
Prefer the structured metadata configuration for title, description, robots, canonical, Open Graph, Twitter, alternate links, and JSON-LD. Hand-authored duplicates can produce conflicting tags.
Use defer, async, or module scripts when appropriate so a third-party script does not block document parsing.
A syntactically valid source write can still contain broken HTML. Inspect the draft’s rendered document before publishing.
Third-party integrations may have consent, privacy, and data-processing requirements outside Cactal.

Site favicon

Favicons are a current website setting, not a source file. Set a ready PNG, SVG, or ICO asset with PUT /v1/websites/{websiteId}/favicon:

curl -X PUT 'https://api.cactal.ai/v1/websites/V1StGXR8_Z5jdHi6B-myT/favicon' \
  -H "Authorization: Bearer $CACTAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "assetId": "aR7sT9uV1wX3yZ5bC6dE8" }'

The favicon changes immediately on published and draft hosts without a lease or publish. Served pages carry <link rel="icon"> tags for it: a PNG is linked once and doubles as the Apple touch icon, an ICO is linked as is, and an SVG is linked after its rasterized PNG preview so browsers that ignore SVG icons still show one. /favicon.ico redirects to the asset for clients that never read the tags. Send { "assetId": null } to restore the Cactal fallback. A page or redirect explicitly handling /favicon.ico wins over the setting. The dashboard offers the same choice under the site’s Settings. See Upload assets for allowed formats and upload steps.

Validate and publish

For not_found and custom HTML changes:

Read the current head snapshot.
Acquire an edit lease and upsert the singleton.
Wait for the draft preview to become ready.
Inspect a normal page and an unmatched URL on the draft host.
Run POST /v1/websiteSourceCode/head/check.
Publish after the draft behaves correctly.

Custom HTML is not semantically validated. The quality gate confirms source integrity and buildability, but visual and browser verification remains necessary.

Troubleshooting

Problem	Cause	Fix
Custom 404 returns status 200	The request matched a real page	Test an actually unmatched path and check redirects
Custom 404 does not appear	A redirect matches first, or the file uses the wrong route sentinel	Remove the redirect or use `route: 'not_found'`
404 page fails only for some content	A CMS query cannot retrieve published data	Publish the dependency or simplify the query
A verification tag is not found	It was placed after a script that rewrites the head	Move it to `custom_head_start`
A widget runs before the page exists	Its script is too early	Move it to `custom_body_end` or use `defer`
A metadata tag appears twice	It exists in both structured metadata and a custom slot	Keep the structured metadata version and remove the raw duplicate
A source rollback did not restore the favicon	Favicons are current settings	Set the previous favicon asset explicitly

Next steps

Style a website for global_css and Tailwind CSS
Configure SEO metadata for structured head tags
Configure routes and redirects for URL behavior
Preview drafts and versions before publishing third-party code

Get started

Core concepts

Guides

Build with agents

Platform

Customize site-wide files

Site-wide settings at a glance

Create a custom not-found page

Use CMS data on the 404 page

Add custom document HTML

Add a head integration

Add a tag-manager fallback

Raw HTML and security

Site favicon

Validate and publish

Troubleshooting

Next steps

​Site-wide settings at a glance

​Create a custom not-found page

​Use CMS data on the 404 page

​Add custom document HTML

​Add a head integration

​Add a tag-manager fallback

​Raw HTML and security

​Site favicon

​Validate and publish

​Troubleshooting

​Next steps

Site-wide settings at a glance

Create a custom not-found page

Use CMS data on the 404 page

Add custom document HTML

Add a head integration

Add a tag-manager fallback

Raw HTML and security

Site favicon

Validate and publish

Troubleshooting

Next steps