Integration best practices
Surreal CMS works with almost any website, but a little structure goes a long way. This page covers the habits that keep pages easy to edit, fast to publish, and free of surprises.
If you're new to Surreal CMS, start with content regions and come back here once your first site is connected.
Content regions
Give every region a stable, unique id
Surreal CMS finds each region in your source by its id, not by its position on the page. Pick
descriptive ids like pricing-intro or footer-hours and leave them alone once the
page is live. Revisions are stored by id, too, so a renamed region can't be restored from older
revisions.
Ids must be unique on the page. When two elements share an id, only one of them is saved when you publish.
Wrap the content, not the layout
Keep grids, columns, and wrappers outside the region so editors can change the content without touching the structure around it.
<div class="container">
<div class="column">
<div id="intro" class="cms-editable">
<p>Editors change this.</p>
</div>
</div>
</div>
Layout classes belong on the region element or its wrappers. Anything inside the region is content, and editors can rewrite it.
Make regions as big as the content allows
Content that flows from top to bottom, such as a heading, a lead paragraph, body copy, an image, and a pull quote, works best as one block region. Editors can rewrite it, reorder it, and add or remove paragraphs, images, and quotes with the toolbar, which is what most people expect from a CMS.
<div id="about" class="about cms-editable">
<h1>About the bakery</h1>
<p class="lead">We bake everything here, every morning.</p>
<img src="uploads/ovens.jpg" alt="The ovens at 5am">
<p>It started with one oven and a lot of flour.</p>
<blockquote><p>The best rye in town.</p></blockquote>
</div>
Split content into separate regions only where something in between isn't content, such as columns, a background image, a gallery, or a component whose structure has to stay put. A region for every heading, paragraph, and image works, but it stops editors from adding anything new and makes the page harder to change. Save that for pages that really need to be locked down.
Style content in a large region by element, such as .about h2 and
.about blockquote, so anything an editor adds looks right. Classes already in the region are
kept, but editors can't add new ones.
Choose the element that matches the content
The element you tag decides which editor and toolbar people get.
-
Use a
<div>,<section>, or other block element for rich content. - Use a heading,
<p>, or<span>for a single line. - Use an
<img>for an image and an<a>for a button or link. -
Add
data-type="text"for plain text such as prices, phone numbers, and dates, where formatting would only get in the way.
Some elements can't be regions, including <table>, <pre>,
<form>, <video>, <picture>, and
<svg>. Wrap them in a <div> and make the
<div> editable instead. The content regions page
lists every supported element.
Keep regions side by side
A region inside another region is ignored, and its cms-editable class is removed the next time
the outer region is saved. Put regions next to each other instead. Background regions are the one exception:
they can hold other regions.
Markup inside regions
Stick to plain HTML
The editor cleans up content when it's saved, so markup it doesn't understand won't survive. Inside a region:
-
Inline
<svg>is removed. Use an<img>that points to an SVG file. - Custom elements and web components are removed. Keep them outside of regions.
-
Empty elements, such as
<i class="icon"></i>icon fonts and empty paragraphs, may be removed. Use images for icons, or add icons with CSS. - Inline event handlers and
javascript:links are removed. -
<b>and<i>become<strong>and<em>.
Keep responsive images outside of image regions
When an editor swaps an image, Surreal CMS updates its src and alt. Other
attributes stay the same. If an image region has a srcset, the browser keeps showing the old
image. Use a plain <img> for editable images, and save srcset and
<picture> for images that live outside of regions.
Use the code block format
Code samples inside a region should use this format. Other classes on the <pre> are
removed when the region is saved.
<pre class="cms-code"><code class="language-css">
.example { color: tomato; }
</code></pre>
Keep code out of regions
Regions hold content, not code. Server-side code inside a region is lost when you publish, because the
editor only sees the rendered page. The same goes for template tags such as {{ title }}.
Scripts inside a region survive, but they run while people edit, which rarely ends well. Put scripts and
server-side code outside of regions. See server-side languages for
more.
Structure
Lock the structure, unlock the words
Cards, team members, events, and menu items share the same markup. Make each one a repeatable, lock it, and unlock only the parts editors should change.
<div id="team" class="cms-editable">
<div class="person cms-repeatable cms-lock">
<img class="cms-unlock" src="uploads/jane.jpg" alt="Jane Smith">
<h3 class="cms-unlock">Jane Smith</h3>
<p class="cms-unlock">Head of support</p>
</div>
</div>
Editors can duplicate, reorder, and remove each person, but they can't break the card. Repeatables and lockables only work inside block and inline regions.
Lock only what has structure to protect. A list where each item is a heading and a paragraph doesn't need it. Plain headings and paragraphs in a block region are easier to edit.
Leave ids out of repeatables and blocks
Duplicating a repeatable copies everything inside it, ids included, so the page ends up with duplicates. Style repeatables with classes instead. Blocks can't have an id on their top-level elements for the same reason.
Treat templates and blocks as starting points
Templates and blocks are copied into a page when they're used. Editing one later doesn't change the pages that already use it. Keep their styles in your stylesheet so every copy looks right. Each site can have up to 100 templates and 100 blocks.
Includes
Keep static includes identical
When you publish a page, its copy of every static include is written to every page you've enabled for that site. The page you publish is the source of truth. To change a shared header or footer, change it on one page and publish that page.
Because of this, every page that shares an include should have the same markup for it. If one page has an older copy, publishing that page brings the older copy back everywhere.
Enable only the pages people edit
Publishing a page with a static include uploads every enabled page on the site. Fewer enabled pages means faster publishing. This matters most over FTP and FTPS, which transfer one file at a time. SFTP and WebDAV transfer ten at a time, and Amazon S3, Cloudflare R2, and DigitalOcean Spaces transfer twenty.
Use relative paths for dynamic includes
Surreal CMS follows PHP includes and Server Side Includes to find regions in other files. Relative paths are resolved from the page's folder and work on any host. Absolute paths only work when your FTP root is also your web root. A few more things to keep in mind:
- Put regions inside the include file, not around the include statement.
- Open and close each tag in the same file.
- Surreal CMS follows the first Server Side Include on each page and doesn't follow nested includes.
Use absolute URLs in shared content
Links and images inside regions are saved as relative URLs. If a region appears on pages in different
folders, such as a region inside a shared include, add data-urls="absolute" so its links work
everywhere.
<footer id="footer" class="cms-include">
<div id="footer-links" class="cms-editable" data-urls="absolute">
<a href="/contact">Contact us</a>
</div>
</footer>
Scripts and the editor
Guard scripts that change the page
The editor loads your real page, and your scripts run there too. If a script changes something inside a region, such as adding a class or filling in text, that change is saved when the editor publishes. Check for the CMS before running scripts like these.
if (!document.documentElement.classList.contains('is-cms')) {
startSlideshow();
}
The is-cms class is on the <html> element from the start.
window.isCMS is set at the end of the <head>, so scripts that run earlier
should check the class. See detecting the CMS for every option.
Show hidden content in the editor
Tabs, sliders, accordions, and modals hide content that editors still need to reach. Use the
is-cms class to show everything while editing.
.is-cms .tab-panel,
.is-cms .slide {
display: block;
}
Put editable content in the HTML
The editor finds regions when the page loads. Content that a script adds later, such as a feed or a widget, can't be edited. If people need to edit it, it has to be in the page's HTML.
Hide scripts with special comments, carefully
To keep a script from running in the editor, wrap it in cms-ignore comments. Write them exactly
as shown, with no spaces inside the comment.
<!--cms-ignore-->
<script src="chat-widget.js"></script>
<!--/cms-ignore-->
Everything between the comments is removed from the editor's copy of the page. Use them outside of regions and static includes. Inside a region, the ignored content is lost when you publish.
Light and dark mode
Follow the system color scheme
We recommend letting the visitor's system setting decide between light and dark mode. Set your colors
once, then set them again in a prefers-color-scheme media query.
:root {
color-scheme: light dark;
--page-background: #ffffff;
--page-text: #1f2937;
}
@media (prefers-color-scheme: dark) {
:root {
--page-background: #111827;
--page-text: #f3f4f6;
}
}
body {
background: var(--page-background);
color: var(--page-text);
}
In the editor, your page follows Surreal CMS instead of the system. When someone chooses Light, Dark, or System from the menu under their avatar, the page switches too, so editors can check their work in both modes without any extra setup.
Set guide colors for both modes, so the editor's outlines stand out in each one.
If your site has a theme toggle
A theme toggle doesn't work well in the editor. It may not respond to clicks there, and when your script picks the mode, editors can't change it from Surreal CMS. To keep a toggle, hide it in the editor and let the page follow the color scheme instead.
.is-cms .theme-toggle {
display: none;
}
Then have your theme script skip the saved choice in the editor and listen for changes, so the page follows along when an editor switches modes.
const root = document.documentElement;
const systemDark = window.matchMedia('(prefers-color-scheme: dark)');
function applyTheme() {
const saved = root.classList.contains('is-cms') ? null : localStorage.getItem('theme');
root.classList.toggle('dark', saved ? saved === 'dark' : systemDark.matches);
}
applyTheme();
systemDark.addEventListener('change', applyTheme);
Put the theme class or attribute on <html>. Guide colors can't follow a class on
<body>.
Metadata
Surreal CMS manages each page's title, description, robots tag, and Open Graph tags from the metadata panel, and writes them every time you publish. Keep these tags as plain HTML in your source, not generated by server-side code, or they'll be overwritten. The Open Graph title and description follow the page's title and description.
Pages are published as UTF-8, and Surreal CMS sets the charset tag for you. Save your files as UTF-8 too, so special characters survive the trip.
Upload folder
Give uploads their own folder
The upload folder is the only part of your server that users can change from Surreal CMS. They can upload, rename, move, and delete anything in it, but nothing outside of it. The file manager and the editor's image and link pickers show that folder and nothing else, and the server refuses changes anywhere else. So the folder you choose decides what your users can touch.
Create a folder called uploads in your home folder and choose it as the upload folder when you
connect your website. Keep pages, stylesheets, scripts, and anything else you
don't want renamed or deleted out of it. If the upload folder is your home folder, users see every file
on your website and can rename or delete your pages and folders. Deleted files can't be recovered.
Link to images from that folder in your HTML, such as uploads/hero.jpg, so the files your users
manage are the ones they see in the editor. An existing images folder works too, as long as
nothing but images lives in it. Scan for Pages skips the upload folder.
The upload folder covers files, not pages. Users can still delete pages from the Pages list, which removes the file from your server. Turn off Delete pages in Site Settings if they shouldn't.
Keep uploads public
Make sure the upload folder is publicly reachable. Surreal CMS reads uploaded images from your website to create gallery thumbnails, so a private upload folder means missing thumbnails.
Hosting
Keep pages reachable
The editor loads your live page from our servers, just like a visitor would. Pages behind HTTP
authentication, an IP allowlist, or bot protection can't be loaded. If your host blocks unknown
traffic, allow our IP address,
162.243.9.115.
These requests include a Client-Id: clientcms header and a current Chrome user agent. If your
bot protection can only match on headers, match on Client-Id, not the user agent. The IP
address is safer to allow, because anyone can send a header.
Go easy on HTML caching
If a CDN or caching plugin holds on to your HTML, the editor may load an older copy of the page. Turn off caching for HTML files or keep it short. The Amazon S3 & CloudFront guide shows one way to set this up.
Use HTTPS and allow cross-origin fonts
The editor runs on a secure connection, so stylesheets and scripts served over plain HTTP won't load in it. Web fonts and JavaScript modules load from a different origin in the editor, too, so your server needs to allow that with CORS headers. Here's how to enable cross-domain fonts.
Developer API
The developer API manages sites, pages, users, and permissions. Pages are still edited and published in the editor.
- Store the ids the API returns. They never change, so you won't have to search for objects again.
- Page through lists with
limitandoffset. The largest page size is 1,000. - Stay under 10 requests per second.
- Keep your Personal Access Token on your server, out of browsers and source control.
- Permissions are replaced, not merged. Get a user's current permissions, change them, and send the whole list back.
-
To invite a user without setting a password, send a
messageinstead. They'll get an email with an activation link.
Test before you hand it off
Open each page in the editor before you invite anyone. Guides point out regions with problems, such as a missing id, a duplicate id, or an unsupported element. The source editor underlines the same problems in your code. Then publish a small change and check the live page.