Skills for building AEM Edge Delivery Services sites — site creation, block development, content modeling, code review, testing, and page import.
91%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
The rules for the HTML that Experience Workspace (formerly DA) stores and the
Edge Delivery pipeline turns into a page. They apply whatever the API backend
(DA or Source Bus) or hostname, and also to hand-written pages in ./content/ served by
aem up (see aem-cli). Everything below was checked against a live
preview; wrong markup fails silently, with no error.
The upload and preview rules below are for the DA source API (admin.da.live).
Some sites keep their authored content in Source Bus (api.aem.live); see
Source Bus. Find the store in the site config
(content.source.type: markup is DA, sourcebus is Source Bus) or ask the
user; fstab.yaml is deprecated. If admin.da.live calls fail or find nothing
in a site the user says has content, it may be on Source Bus. See da-auth
for credentials.
<body><header></header><main>
<div>
<h1>Title</h1>
<p>Intro</p>
<div class="cards"><div><div>cell</div><div>cell</div></div></div>
</div>
<div>
<div class="metadata"><div><div>title</div><div>My page</div></div></div>
</div>
</main><footer></footer></body><main> is required (sections with no <main> around them preview empty);
<body>, <header> and <footer> are optional, and text placed in header
or footer is dropped.<main>. Elements placed directly in <main> are dropped. A div placed
there is taken as a section, so a block or metadata div there is not a
block: its rows become paragraphs. <hr> also starts a new section.id, class, style, data-* on default content are dropped;
headings get an id from their text. Empty <p> is dropped.<div class="name variant">, one child div per row, one grandchild
div per cell. Table form: header row <td colspan="N">Name (variant, …)</td>
then rows. Use letters, digits and single hyphens for names. The pipeline
turns Feature_Block into feature-block and columns (v) into
columns v; don't rely on it.<table> in default content becomes a block named after its
first cell and that header row is consumed. Never use a bare table for
data; make it a block.Inside the section it styles: <div class="section-metadata"> with rows of
key / value (style = dark, highlight). The class is one token, exactly
section-metadata. class="Section Metadata" makes a different block and the
metadata is silently lost; the table form with header text Section Metadata
is fine. Keys are used as typed.
<div class="metadata"> inside its own section, conventionally last. Rows:
title → <title>; description → description, og and twitter; og:title
also sets twitter:title; image → og and twitter image (absolute URL);
tags → one article:tag per comma value; any other key → <meta name>
with the key lowercased and spaces turned into hyphens (my custom →
my-custom). Canonical, og:url and twitter:card are added. Don't author
og/twitter rows yourself.
Write :name: as text. The pipeline turns any :[a-z0-9-]+: into
<span class="icon icon-name"></span>, in default content and block cells,
and the project's decoration loads the SVG from /icons/name.svg. An authored
empty <span class="icon icon-name"> sent by direct PUT also previews as an
icon, but a page opened in the DA editor lost the span, so use :name: for
anything authors will edit. The whitespace around an icon is removed.
<img src> URLs the preview can fetch. They are sideloaded
and delivered as <picture> with webp/jpeg sources at 750 and 2000 px, plus
width, height and lazy loading. Don't hand-author <picture>/<source>;
it is replaced. Repo-relative or document-relative paths
(/images/a.png) become <img src="about:error">. Always set alt.aem.page/aem.live URLs become relative; other
hosts stay. class and target on <a> are dropped, title is kept.
Bold or italic standalone links (<strong><a>) are what decoration turns
into buttons; that is project code, not the pipeline.Kept: strong, em, del, code, u, sub, sup, a. Rewritten: b→
strong, i/mark→em, s→del, kbd→code. Unwrapped (text kept, class
lost): span, ins. Cells: a lone <p> is unwrapped; <br> depends on its
position. Style with classes on the block, not on inline tags.
PUT https://admin.da.live/source/{org}/{repo}/{path}.html with
Authorization: Bearer <IMS token> (see da-auth; aem content manages its
own login in .hlx/.da-token.json, direct API calls follow da-auth) and a multipart
form with the file in field data. Any other field name returns 200 and
writes nothing (the next GET is 404). A missing or bad token returns 401
with an empty body.POST https://admin.hlx.page/preview/{org}/{repo}/main/{path-without-.html}
with the same Bearer token, then /live/ to publish. Uploading alone does
not change aem.page.data=@file;type=image/png). aem content push reports ✓ for PNG/SVG but writes nothing; upload binaries
with the PUT. Pages pushed by the CLI do arrive.AEM_BACKEND_SVG_TOO_BIG.Same HTML rules as above; different calls, all with the da-auth Bearer token:
PUT https://api.aem.live/{org}/sites/{site}/source/{path}.html with
the raw body and Content-Type: text/html (--data-binary @file), not DA's
multipart form. A page with external images returns 400: POST it instead so
the images are interned. GET reads it; a trailing / lists a folder.POST https://api.aem.live/{org}/sites/{site}/preview/{path}
and .../live/{path} (path without .html, no main segment). The legacy
POST admin.hlx.page/preview/{org}/{site}/main/{path} fails on these sites
(404 No handler found for document).
GET .../status/{path} shows the state.[], and a Source Bus
site can keep stale pages in admin.da.live: an empty or populated listing
does not identify the store; the site config does.After the preview POST, GET https://admin.hlx.page/preview/{org}/{repo}/main/{path}.md
with header x-auth-token: <IMS token> returns the markdown the pipeline
built from your HTML: dropped content, lost spans and blocks that didn't
form show up there, even when aem.page needs site authentication.
references/media.md: where binaries live (/media,
dot-folders), which types are delivered, size caps. Carried over from the
previous version, not re-verified except where marked.
.tessl-plugin
skills
aem-block-library
aem-cli
aem-layout-view
block-collection-and-party
brand-setup
references
building-blocks
code-review
content-driven-development
references
content-modeling
create-site
da-auth
figma-to-content
find-test-content
generate-import-html
identify-page-structure
migrate-header
page-decomposition
page-import
preview-import
scrape-webpage
slicc-handoff
snowflake
assets
substrate
substrate-milo
examples
knowledge
scripts
testing-blocks
ue-component-model