# Integration reference

How to mark up HTML so Surreal CMS can edit it. Everything here is plain HTML: classes, ids, and `data-` attributes. There's no script to include and nothing to install on the server.

Source: https://www.surrealcms.com/docs/content-regions and the pages it links to.

## How the editor sees a page

- Surreal CMS downloads the page's source over the site's connection, loads the live page in the editor, and publishes by rewriting only the regions, includes, and metadata it manages. Everything else in the file is left as it was.
- Nothing is editable until you tag it. Editors can only change the parts of the page you've explicitly marked.
- Regions are matched by `id` when publishing, not by position. Revisions are stored by `id` too.
- The editor runs the page's own CSS and JavaScript. Scripts that change a region's DOM will have those changes published.

## Content regions

A content region is any supported element with a unique `id` and the `cms-editable` class.

```html
<div id="content" class="cms-editable">
  <p>Everything inside is editable.</p>
</div>
```

The element decides the region type and the toolbar editors get.

| Type       | Elements                                                                                                                                        | Notes                                                                                                                                                              |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Block      | `address article aside blockquote dd div dt fieldset figure footer header hgroup li main nav ol section td th ul`                               | Full toolbar: headings, lists, images, tables, blocks, galleries, embeds. Use for rich content.                                                                    |
| Inline     | `abbr acronym b big caption cite code del dfn em figcaption h1 h2 h3 h4 h5 h6 i ins kbd label mark p q s samp small span strong sub sup tt var` | Limited toolbar. Can't contain headings, paragraphs, or lists. Use for one line.                                                                                   |
| Image      | `img`                                                                                                                                           | Only `src` and `alt` are written on publish.                                                                                                                       |
| Link       | `a`                                                                                                                                             | Content plus `href`, `title`, `target`, and `rel` are written. Setting a target adds `rel="noopener"`. No block-level children.                                    |
| Background | any element with `data-type="background"`                                                                                                       | Edits inline `background-color` and `background-image` (and `background-size`, `background-repeat`). Its content isn't editable, but it may contain other regions. |
| Gallery    | `div`, `ul`, `ol` with `data-type="gallery"`                                                                                                    | A fixed image gallery. See below.                                                                                                                                  |
| Text       | any supported element with `data-type="text"`                                                                                                   | Plain text only (`<br>` allowed). Use for prices, phone numbers, dates.                                                                                            |

Elements that aren't in these lists can't be regions. That includes `<table>`, `<pre>`, `<form>`, `<video>`, `<picture>`, `<svg>`, `<iframe>`, and `<body>`. Wrap them in a `<div>` and make the `<div>` the region.

### How big to make a region

Make regions as big as the content allows. A run of content that flows top to bottom, such as a kicker, a heading, a lead paragraph, body copy, an image, a pull quote, and a list, belongs in one block region, even if the design styles each part differently. Editors can then rewrite it, reorder it, and add or remove paragraphs, images, and quotes with the toolbar. That's what most clients want, and it's how the editor works best.

Split content into separate regions only where something in between isn't content:

- Columns, grids, and wrappers that position things side by side. Put a region in each column, not around the grid.
- Markup the editor would break: a background image, a gallery, a button with its own classes, or a component whose structure must survive, such as a card with an image, a title, and a link in fixed positions.
- Content that needs a different region type, such as plain text (`data-type="text"`) for prices, phone numbers, and hours, or a link region for a call to action outside the copy.
- Shared content. Regions inside a static include are separate from the page's own regions.

Don't tag each heading, paragraph, image, or quote separately, and don't wrap plain text in repeatables and locks. Headings followed by paragraphs are just content. Lock content down that tightly only when the user asks for it, such as a client who must not change a page's structure.

```html
<!-- Too granular: four regions and a locked list for one column of content -->
<header class="page-intro">
  <p id="intro-kicker" class="kicker cms-editable" data-type="text">Already here</p>
  <h1 id="intro-title" class="cms-editable">You don't need to bring the house with you.</h1>
  <p id="intro-lead" class="lede cms-editable">Linen, a lamp, something to drink from.</p>
</header>
<div id="amenities" class="cms-editable">
  <article class="cms-repeatable cms-lock">
    <h2 class="cms-unlock">The bed</h2>
    <p class="cms-unlock">Linen, a lighter blanket, and a heavier one in the chest.</p>
  </article>
</div>

<!-- Better: one region -->
<div id="intro" class="page-intro cms-editable">
  <p class="kicker">Already here</p>
  <h1>You don't need to bring the house with you.</h1>
  <p class="lede">Linen, a lamp, something to drink from.</p>
  <h2>The bed</h2>
  <p>Linen, a lighter blanket, and a heavier one in the chest.</p>
</div>
```

Write the CSS for a large region so it holds up when editors change it:

- Style by element under the region's class (`.page-intro h2`, `.page-intro blockquote`, `.page-intro img`), so a paragraph, quote, or image an editor adds looks right without a class.
- Classes already on elements inside a region are kept, but editors can't add them. Use them for touches like a kicker or a lead paragraph, and make sure the content still reads well without them. Selectors such as `.page-intro > p:first-child` work too.
- Style every element the toolbar can produce. See "Markup the editor rewrites" below.

### Region rules

- **Unique, stable ids.** Every region needs an `id` that's unique on the page. Use descriptive ids like `pricing-intro` or `footer-hours`, and never rename one after launch; renamed regions lose their revision history. If two elements share an id, only the first is updated.
- **No nesting.** A region inside another region is ignored, and its `cms-editable` class is removed the next time the outer region is saved. Put regions side by side. The only exception: a background region may contain other regions, but a background region can't sit inside another region.
- **Wrap content, not layout.** Keep grids, columns, and wrappers outside the region, and make the region as big as the content between them. Layout classes can go on the region element itself, but everything inside it is content that editors can rewrite.
- **No code inside regions.** Server-side code (`<?php ?>`, `<% %>`, Razor) and template tags (`{{ }}`, `{% %}`) inside a region are lost on publish, because the editor only sees the rendered page. `<script>` inside a region survives but runs while people edit. Keep all of it outside regions.
- **Content must be in the HTML.** Regions are found when the page loads. Content injected later by JavaScript can't be edited.

### Markup the editor rewrites

The editor cleans content when it's saved, so markup it doesn't understand won't survive inside a region.

- Inline `<svg>` is removed. Use `<img src="icon.svg">`.
- Custom elements and web components are removed. Keep them outside regions.
- Empty elements such as `<i class="icon"></i>` and empty paragraphs may be removed. Use images, or add icons with CSS.
- Inline event handlers (`onclick`) and `javascript:` URLs are removed.
- `<b>` and `<i>` become `<strong>` and `<em>`.
- Loose text in block regions is wrapped in `<p>`. If spacing matters, style `.cms-editable p`.
- Code samples must use `<pre class="cms-code"><code class="language-xyz">…</code></pre>`. Other classes on `<pre>` are dropped.
- Images with captions are written as `<figure class="image"><img …><figcaption>…</figcaption></figure>`. Aligned images get `align-left`, `align-right`, or `align-center`. See "Image alignment" below.
- Embeds are written as `<div class="cms-embed">…</div>`, with the embed code kept exactly as entered. With the panel's "Fit to width" option on (the default, and always for links pasted into the page), the editor adds `style="width: 100%; height: auto; aspect-ratio: W / H"` to the embed's `<iframe>`, `<video>`, `<embed>`, or `<object>`, using the element's own width and height attributes.
- Anchors are written as an `id` on a heading or other block, such as `<h2 id="pricing">`. Editors can add, rename, and remove ids inside a region, so hang CSS and scripts on classes instead.

Style every element an editor can produce inside a block region: `h1`–`h6`, `p`, `ul`, `ol`, `blockquote`, `pre`, `table`, `figure`, `figcaption`, `hr`, `strong`, `em`, `del`, `sup`, `sub`, `code`, `mark`, `small`, and the alignment classes above.

### Image alignment

Editors can align an image they insert into a block region. The image panel offers None, Left, Center, and Right, and the toolbar's alignment button works on a selected image too. Image regions, gallery images, and images in your own markup outside regions have no alignment option.

What the editor writes depends on whether the image has a caption:

```html
<!-- Plain images get a class and inline styles -->
<img src="uploads/a.jpg" alt="…" class="align-left" style="float: left;" />
<img src="uploads/b.jpg" alt="…" class="align-right" style="float: right;" />
<img src="uploads/c.jpg" alt="…" class="align-center" style="display: block; margin-left: auto; margin-right: auto;" />

<!-- Captioned images get the class on the figure and nothing else -->
<figure class="image align-left">
  <img src="uploads/d.jpg" alt="…" />
  <figcaption>Caption</figcaption>
</figure>
```

None removes the class and the inline styles. Tables get the same classes. Paragraphs and headings are aligned with an inline `text-align` instead, so the `align-*` classes only ever appear on images, figures, and tables.

The site's CSS has to finish the job:

- A captioned image has no inline styles, so it won't move unless the site styles `figure.image.align-*`.
- A plain floated image has no margin, so text runs right up against it.
- The inline `float` beats any stylesheet rule without `!important`, which matters if aligned images should stack on small screens.
- A float at the end of a region hangs out of it unless the region contains its floats.

Add rules like these to every site with a block region. Scope them to the class that already styles the site's rich content (`.content` here), not to every image on the site. Adjust the widths and spacing to the design.

```css
/* Images an editor aligns in a block region */
.content {
  display: flow-root; /* contain floated images */
}

.content img {
  max-width: 100%;
  height: auto;
}

.content figure.image {
  margin: 1.5em 0;
}

.content figure.image img {
  display: block;
}

.content .align-left {
  float: left;
  max-width: 50%;
  margin: 0.25em 1.5em 1em 0;
}

.content .align-right {
  float: right;
  max-width: 50%;
  margin: 0.25em 0 1em 1.5em;
}

.content .align-center {
  width: fit-content;
  margin-inline: auto;
}

/* Stack aligned images on small screens. !important beats the inline float on plain images. */
@media (max-width: 40rem) {
  .content .align-left,
  .content .align-right {
    display: block;
    float: none !important;
    max-width: 100%;
    margin-inline: auto;
  }
}
```

Don't use `align-left`, `align-right`, or `align-center` for anything else inside a block region, since the editor adds and removes them.

### Image regions

```html
<img id="hero-photo" class="cms-editable" src="uploads/hero.jpg" alt="Our storefront" />
```

Only `src` and `alt` are updated. Don't put `srcset`, `sizes`, `width`, or `height` on an image region, and don't put one inside `<picture>`; the browser would keep showing the old image. Size editable images with CSS. Use `srcset` and `<picture>` only for images outside regions.

### Link regions

```html
<a id="cta-button" class="cms-editable button" href="contact.html">Book a table</a>
```

Good for buttons and calls to action. The link text, `href`, `title`, `target`, and `rel` are editable. Don't put block elements inside.

### Background regions

```html
<section id="hero-bg" class="cms-editable hero" data-type="background" style="background-image: url(uploads/hero.jpg);">
  <h1 id="hero-title" class="cms-editable">Fresh bread daily</h1>
  <p id="hero-text" class="cms-editable">Open 7 days a week.</p>
</section>
```

The editor changes the region's inline background: image, color, size, repeat, position (the focal point of a cropped image), and an overlay. On publish, the `background` declarations in the `style` attribute are replaced with what the editor had, and everything else in the attribute is kept. The overlay is a solid tint written as a gradient layer directly over the image, like `linear-gradient(rgba(0, 0, 0, .5), rgba(0, 0, 0, .5)), url(uploads/hero.jpg)`; write a tint that way and editors can adjust its color and strength. Any other gradient over the image (angled, multi-stop, radial) is kept exactly as written and isn't editable. A background set only in a stylesheet is editable too; the edits are written inline. Tag the text inside as its own regions.

### Gallery regions

```html
<div
  id="work-gallery"
  class="cms-editable"
  data-type="gallery"
  data-thumbnail-width="400"
  data-thumbnail-height="300"
  data-thumbnail-resize="trim"
>
  <a href="uploads/photo-1.jpg">
    <img src="uploads/thumbnails/photo-1-400x300.jpg" alt="Kitchen remodel" data-caption="Kitchen remodel" />
  </a>
</div>
```

| Attribute               | Default | Meaning                                                                   |
| ----------------------- | ------- | ------------------------------------------------------------------------- |
| `data-thumbnail-width`  | `256`   | Thumbnail width, up to `2000`.                                            |
| `data-thumbnail-height` | `256`   | Thumbnail height, up to `2000`.                                           |
| `data-thumbnail-resize` | `fit`   | `fit` scales within the box. `trim` fills the box and crops the overflow. |
| `data-captions`         | `true`  | Store captions in `data-caption` on each image.                           |
| `data-links`            | `true`  | Wrap each thumbnail in a link to the full image.                          |

Gallery images must use exactly the markup above. Extra elements, classes, and attributes are removed. In a `<ul>` or `<ol>` gallery, each image is wrapped in `<li>`. Thumbnails are generated into `[upload folder]/thumbnails/` by fetching each image from the live site, so the upload folder must be publicly reachable. Lightbox-style scripts go outside the region.

Editors can also insert a gallery into any block region. Those galleries use `<div class="cms-gallery">` and are configured on the containing region with `data-gallery-thumbnail-width`, `data-gallery-thumbnail-height`, `data-gallery-thumbnail-resize`, `data-gallery-captions`, `data-gallery-links`, and `data-gallery-element` (`div`, `ol`, or `ul`).

### Text regions

```html
<span id="phone" class="cms-editable" data-type="text">(555) 010-0199</span>
```

### Absolute URLs

Links and images inside regions are saved as relative URLs. Add `data-urls="absolute"` to a region that appears on pages in different folders, such as one inside a shared include, so its links work everywhere.

```html
<div id="footer-links" class="cms-editable" data-urls="absolute">…</div>
```

## Repeatables

Add `cms-repeatable` to any element inside a block or inline region. Editors can duplicate, reorder, and delete it as a unit.

```html
<ul id="menu-items" class="cms-editable">
  <li class="menu-item cms-repeatable">…</li>
</ul>
```

- Repeatables only work inside block and inline regions.
- Don't put `id` attributes on or inside a repeatable. A duplicated item leaves its ids behind, so only the original keeps them. Style with classes.
- Always ship at least one instance. An editor can't create a repeatable from nothing.
- Repeatables can also be used inside blocks.

## Lockables

Add `cms-lock` to an element inside a block or inline region to make it uneditable. Add `cms-unlock` to descendants that should be editable again. A locked element can still be deleted.

```html
<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>
    <a class="button" href="mailto:hello@example.com">Email</a>
  </div>
</div>
```

`cms-repeatable cms-lock` with `cms-unlock` on the parts editors change is the standard pattern for repeated components with structure: cards in a grid, team members, events, testimonials, pricing tiers, menu items, and navigation links. Editors can add, reorder, and remove cards, and change the words and images, but can't break the card's structure.

Use it only where there's markup to protect. A list that's only a heading and a paragraph per item doesn't need it; write plain headings and paragraphs in a block region and style them. See "How big to make a region" above.

- `cms-lock` must be inside a block or inline region.
- `cms-unlock` must be inside a `cms-lock` element.
- An unlocked `<img>` lets editors swap the image. An unlocked `<a>` lets them change its text and link.

## Includes

### Static includes

Shared markup such as a header, nav, or footer. Add an `id` and `cms-include` to the element.

```html
<footer id="site-footer" class="cms-include">
  <p id="footer-text" class="cms-editable">© Example Bakery</p>
</footer>
```

- On publish, the element's inner HTML is copied to the element with the same `id` and `cms-include` on every **enabled** page on the site, and to matching includes in the site's templates. Attributes aren't copied. Pages that aren't enabled aren't touched.
- The page you publish always wins. Every page that shares an include must start with identical markup for it, or publishing an out-of-date page will spread the old copy everywhere.
- Publishing a page with a static include re-uploads every enabled page. That's slow over FTP and FTPS (one file at a time). SFTP and WebDAV do 10 at a time; S3, R2, and Spaces do 20. Enable only the pages people edit.
- Includes may contain regions but don't have to. Regions inside an include that appears in different folders need `data-urls="absolute"`.
- Don't use `<!--cms-ignore-->` inside a static include.

### Dynamic includes

On servers that run PHP or Server Side Includes, Surreal CMS follows the include to find regions that aren't in the page itself.

```php
<?php include 'includes/footer.php'; ?>
```

```html
<!--#include virtual="includes/footer.html" -->
```

- Supported: PHP `include`, `require`, `include_once`, `require_once` with a quoted literal path, and SSI `file=` or `virtual=`. No variables or constants in paths (`include __DIR__ . '/footer.php';` fails). ColdFusion and Lucee aren't supported.
- Use paths relative to the page's folder. Absolute paths (`$_SERVER['DOCUMENT_ROOT']`, `virtual="/…"`) resolve from the connection's root folder and only work when that's also the web root.
- Only the first SSI on a page is followed. Nested includes aren't followed.
- Put regions inside the include file, never around the include statement.
- Open and close every tag in the same file. Don't open `<body>` in `header.php` and close it in `footer.php`.
- A region that can't be found in the page or its includes isn't written to the file. Publishing reports it as "Failed to locate content region", and its content is kept only in the revision. See https://www.surrealcms.com/docs/errors/content-region-not-found.

## Metadata

These tags are managed from the editor's metadata panel and written on every publish, replacing whatever is in the source. Missing tags are added to `<head>`.

- `<title>` and `og:title` (always the same value)
- `<meta name="description">` and `og:description` (always the same value)
- `og:image`
- `og:type` (kept if present, otherwise `website`; source editor only)
- `og:url` (kept if present, otherwise the page URL; source editor only)
- `<meta name="robots">`: set to `noindex,nofollow` when ticked; removed when not, including any value you wrote yourself
- `<meta charset="utf-8">` is set automatically

Write these as plain static HTML in the source. Never generate them with server-side code; they'll be overwritten. Don't rely on a custom robots value. Save every file as UTF-8.

## Server-side languages

- Outside regions, PHP (`<?php ?>`), ASP (`<% %>`), and Razor (`@{ }`) are protected on publish.
- Template tags such as `{{ }}` and `{% %}` aren't protected and may not survive publishing. Don't use them on pages edited with Surreal CMS.
- PHP inside an attribute value is fine when the code is entirely inside the quotes: `class="<?php echo $c ?>"`. Don't use PHP to add or remove whole attributes.
- Over WebDAV, the WebDAV URL must serve files without executing them, or Surreal CMS downloads the rendered output instead of the source.

## Scripts and the editor

When a page is open in the editor:

- `<html>` has the class `is-cms` from the start. Safe to check at any time.
- `window.isCMS` is `true`, but only after the end of `<head>`. Scripts in `<head>` should check the class.
- `<meta name="is-cms" content="true">` is present.
- Everything between `<!--cms-ignore-->` and `<!--/cms-ignore-->` is removed from the editor's copy. Write the comments exactly like that, with no spaces. They can't nest. Never use them inside a region or a static include; the ignored content is lost on publish. `cms-disable` is the deprecated spelling.

Guard scripts that change regions, and reveal hidden content so editors can reach it:

```js
if (!document.documentElement.classList.contains('is-cms')) {
  startSlideshow();
}
```

```css
.is-cms .tab-panel,
.is-cms .slide,
.is-cms .accordion-body {
  display: block;
}
```

Keep chat widgets, analytics, cookie banners, and popups out of the editor with `cms-ignore` comments placed outside every region.

## Light and dark mode

Not every site needs a dark mode. If this one has it, follow the system color scheme: set colors once, then again in a `prefers-color-scheme: dark` query.

```css
:root {
  color-scheme: light dark;
  --page-background: #ffffff;
  --page-text: #1f2937;
}

@media (prefers-color-scheme: dark) {
  :root {
    --page-background: #111827;
    --page-text: #f3f4f6;
  }
}
```

In the editor, the page's `prefers-color-scheme` follows the Surreal CMS app's theme (Light, Dark, or System in the avatar menu), not the OS. A site that follows the color scheme switches with the app, so editors can check both modes with no extra work.

A theme toggle works against this. It may not respond to clicks in the editor, and a script that picks the mode locks editors into it. If the user wants a toggle, hide it in the editor and make the theme script ignore the saved choice there and follow the color scheme, listening for changes:

```css
.is-cms .theme-toggle {
  display: none;
}
```

```js
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);
```

Run it in `<head>` to avoid a flash of the wrong mode, and check the `is-cms` class rather than `window.isCMS`, which isn't set yet. Put the theme class or attribute on `<html>`, never `<body>`, so the guide colors below can follow it.

## Editor guides

The editor draws guides over the page so editors can see what they can change. Regions get a solid 2px outline 4px outside the element. Repeatables get a dashed 1px outline at their edge. Hovering shows the same outline at a third of its strength. By default, region guides use the app's blue and repeatables use amber. Neither color knows anything about the site's design, so set your own on every site you build.

- `--cms-guide-color` colors region outlines, selected images, rules, and locked elements, the outline shown while dragging, and selected table cells.
- `--cms-repeatable-color` colors repeatable outlines.

Put both in the site's main stylesheet next to its other color tokens. They do nothing outside the editor.

```css
:root {
  --cms-guide-color: #0f766e; /* brand teal, 5.5:1 on white */
  --cms-repeatable-color: #c2410c; /* orange, 5.2:1 on white */
}

@media (prefers-color-scheme: dark) {
  :root {
    --cms-guide-color: #2dd4bf; /* 9.5:1 on #111827 */
    --cms-repeatable-color: #fb923c; /* 7.8:1 on #111827 */
  }
}
```

Set them on the root element. `:root` and `html` work, including with a class or attribute, such as `:root.dark` or `html[data-theme="dark"]`. Anywhere else, such as `body.dark`, has no effect. If the site switches themes with a class on `<body>`, move the switch to `<html>` or the guides can't follow it. Declare dark values wherever the site switches its other colors, whether that's a `prefers-color-scheme` query, a class, or an attribute.

To choose the colors:

- Start from the brand's primary or accent color. When it lacks contrast, use a darker shade of it in light mode and a lighter shade in dark mode rather than an unrelated color.
- Outlines are drawn outside the element, on the parent's background. Aim for at least 3:1 contrast (WCAG non-text contrast) against every background a region sits on: the page, colored bands, hero images, cards, and the footer. Repeatable outlines are 1px and dashed, so aim for 4.5:1.
- One value covers the whole page. If a page mixes light and dark sections, choose colors with a relative luminance between about 0.10 and 0.30, which reach 3:1 against both white and black.
- Use clearly different hues for regions and repeatables, such as a cool guide color and a warm repeatable color, so editors can tell an item from the region around it. Vary the lightness too, for colorblind editors.
- Avoid colors the design already uses for borders, dividers, or focus rings near regions, or the guides blend in. Avoid red, which reads as an error.
- Use opaque colors. Hover already fades them.

## Templates and blocks

- **Templates** are full page sources (name, description, file extension, source) used to create new pages. **Blocks** are HTML chunks editors insert into block regions from the **+** menu.
- Both are copied when used. Changing one later doesn't update pages that already used it.
- Up to 100 of each per site.
- Blocks can't have an `id` on their top-level elements. Avoid ids anywhere in a block, for the same reason as repeatables.
- Block and template styles must live in the site's stylesheet.
- Blocks can contain repeatables and lockables. A block wrapped in `cms-lock` with `cms-unlock` parts is a reliable way to let editors add a styled component, such as a callout, pricing card, or FAQ item, without breaking it.
- Templates should contain the same static includes as the site's pages; matching includes in templates are updated when a page is published.

## Hosting requirements

- The editor loads the live page from Surreal CMS's servers. Pages behind HTTP auth, IP allowlists, or bot protection can't be loaded. Allow `162.243.9.115`. The requests also send a `Client-Id: clientcms` header and a current Chrome user agent, so bot protection that only matches headers can allow `Client-Id` instead.
- Serve pages over HTTPS. HTTP stylesheets and scripts won't load in the editor.
- Web fonts and JavaScript modules load cross-origin in the editor, so the server must send CORS headers for them (for example `Access-Control-Allow-Origin: *` on font files).
- Don't cache HTML for long at a CDN, or the editor may load an old copy.
- The upload folder must be inside the home folder and publicly reachable. Best practice is a dedicated `uploads` folder with no pages in it, and images linked from there (`uploads/hero.jpg`). Editors can upload, rename, move, and delete anything in the upload folder but nothing outside it, so the folder decides what they can touch. Thumbnails are written to `[upload folder]/thumbnails/`. See [connecting.md](connecting.md).

## Legacy classes

Old sites may use these. Replace them with the new syntax when you touch a page.

| Legacy                                                                             | Use instead                            |
| ---------------------------------------------------------------------------------- | -------------------------------------- |
| `editable`, `cushycms`, `cushycms-wysiwyg`, `clienteditor`, `clienteditor-wysiwyg` | `cms-editable`                         |
| `editable-text`, `cushycms-text`, `clienteditor-text`, `cms-editable-text`         | `cms-editable` + `data-type="text"`    |
| `editable-gallery`                                                                 | `cms-editable` + `data-type="gallery"` |
| `repeatable`                                                                       | `cms-repeatable`                       |
| `uneditable`                                                                       | `cms-lock`                             |
| `<!--cms-disable-->`                                                               | `<!--cms-ignore-->`                    |

## Checklist before handing a page to an editor

Run `scripts/check.py` on the file, then confirm:

- [ ] Content that flows top to bottom is one block region, not a region per heading, paragraph, image, or quote.
- [ ] Repeatables and locks protect real structure, not plain headings and paragraphs, unless the user asked for a locked page.
- [ ] Every region, include, and gallery has a unique, descriptive `id`.
- [ ] No region is nested inside another (except inside a background region).
- [ ] Every region uses a supported element; tables, forms, videos, and SVGs are wrapped in a `<div>` region.
- [ ] No `id` on or inside any repeatable, or on a block's top-level elements.
- [ ] `cms-repeatable` and `cms-lock` sit inside a region; `cms-unlock` sits inside `cms-lock`.
- [ ] Image regions have no `srcset`, `sizes`, `width`, or `height`, and aren't inside `<picture>`.
- [ ] No scripts, server-side code, template tags, inline SVG, custom elements, or `cms-ignore` comments inside regions.
- [ ] Static includes are byte-identical on every page that shares them.
- [ ] Title, description, and Open Graph tags are static HTML.
- [ ] Hidden content (tabs, sliders, modals) is revealed with `.is-cms`; scripts that alter regions are guarded.
- [ ] Every element the block-region toolbar can produce is styled, including left, right, and centered images with and without captions.
- [ ] If the site has a dark mode, it follows `prefers-color-scheme`. Any theme toggle is hidden with `.is-cms` and ignores the saved choice in the editor.
- [ ] `--cms-guide-color` and `--cms-repeatable-color` are set on the root, with contrast in light and dark mode.
- [ ] The file is UTF-8, served over HTTPS, and reachable from `162.243.9.115`.
