Content

Make an element a shared section

Saves the element as fragments/<name>.html and replaces it with a reference on the source page and on the pages you include — or, with every_page, puts one reference in the layout instead. All pages change together or none do. Staged as a draft, recorded as one activity event (undo it from there). A retry of a share that already happened answers alreadyApplied. Sharing again under the name of a section that holds this same block adds the pages to it. With selectors, a run of elements next to each other becomes one section inside a wrapper (wrapTag, keepLayout), and every page with the same run gets the reference in its place.

post/api/v1/sites/{slug}/shared-sections

Request

  • Base URL: https://api.dotsy.ai
  • URL: https://api.dotsy.ai/api/v1/sites/{slug}/shared-sections
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer

Path parameters

slugstring required
Example:acme-studio

Site slug or site id (UUID). An old slug answers 301/308 and a site id 307 to the canonical slug path.

Request body

sourceKeystring required

Content key of the page the element is on, e.g. 'about.html'.

selectorstring

CSS selector of the element in the page's stored HTML (the editor's selector, or one checked with get_content?selector=). It must match exactly one element.

ifMatchstring

The page's content hash (analyze's sourceEtag). If the page changed since, nothing is written.

namestring

Name of the new section. Default: analyze's proposedName. A name in use answers 409 section_name_taken.

scope'where_found' | 'every_page'

where_found: each page that has it gets a reference. every_page: one slot in the layout, at the top or bottom of the page content; pages listed in hide don't show it.

keysstring[]

Pages with an exact copy to share it on (analyze's matches.keys). Omit for every exact copy. The source page is always included.

similarstring[]

Pages with a similar copy (analyze's similar.keys) that take the shared version, losing their own wording. Default none.

hidestring[]

every_page only: pages on the layout that should not show it. Default none.

selectorsstring[]

A run of elements that sit next to each other in one parent (only whitespace or comments between), in page order — instead of selector. Each must match exactly one element. The section is the run inside one wrapper (wrapTag); the pages that hold the same run (the same elements, in the same order, next to each other) take it.

wrapTag'div' | 'section' | 'footer' | 'header' | 'article' | 'aside'

With selectors: the wrapper element. Default footer when the run is the last of the page content, else section.

keepLayoutboolean

With selectors: give the wrapper style="display:contents" so a flex or grid parent still lays out the run's elements as before. Default true.

Response

Shared (staged as a draft).

namestring required
keystring required
scope'where_found' | 'every_page' required
pagesinteger required

Pages that show it now.

hiddeninteger required

every_page: pages on the layout that hide it.

writtenstring[] required

Every content key this call staged (or, on a dry run, would stage): the section file, pages, the layout. Staged as a draft; in live publishing mode the dashboard then publishes exactly these keys.

alreadyAppliedboolean required

True on a retry of a share that already happened: nothing was written.

eventIdstring nullable required

The activity event of this change — undo with POST …/activity/{eventId}/revert. Null on a dry run, when nothing was written, or when the audit insert failed.

Example response

{
  "key": "fragments/booking-banner.html"
}

Changes

No recorded changes to this operation across all 1 revision of this API.