/da-content

name: da-content
description: "Use this when generating HTML for Adobe Document Authoring (DA, da.live) upload, uploading media binaries to DA, publishing to aem.live, or driving the DA admin API (auth, source PUT, preview/publish). Covers block HTML format (canonical div-class form and accepted table alternate), section structure, page and section metadata, icons, links, images, default content, document skeleton constraints, block cell content normalization, the DA Source API contract, IMS auth, media storage, supported formats, Media Bus vs Content Bus delivery, and silent-failure rules that corrupt content."
license: Apache-2.0
metadata:
  version: "1.0.1"

DA + EDS content reference

A reference skill — not a workflow. Use it whenever you need to know **what the rules are** for generating, uploading, or delivering content through Adobe Document Authoring (DA) and Edge Delivery Services (EDS).

This skill consolidates rules from three primary surfaces. Load the reference for the task at hand:

| Doing | Read | |---|---| | Generating HTML for DA upload | [references/html-content.md](./references/html-content.md) | | Uploading images, video, PDFs, fonts | [references/media.md](./references/media.md) | | Hitting the DA admin API, auth, preview/publish | [references/platform.md](./references/platform.md) | | Re-verifying asset boundary behavior empirically | [references/fixtures/README.md](./references/fixtures/README.md) |

Every factual claim in the references is tagged `[verified]` (read from code or observed empirically) or `[assumed]` (inferred from documentation without direct verification).

When to use this skill

Invoke this skill whenever you are:

• Generating HTML that will be uploaded to DA (`admin.da.live/source/...`).
• Uploading any binary (PNG, JPG, SVG, MP4, PDF, WOFF2) to DA.
• Calling `admin.da.live` (Source API) or `admin.hlx.page` (preview /

publish API) directly.

• Reading a DA-stored HTML document and modifying it before re-upload.
• Diagnosing why a generated page renders incorrectly on `aem.page` /

`aem.live` (silent failures: `about:error` images, missing meta tags, blocks rendering as plain HTML without their JS or CSS).

When NOT to use this skill

• Writing block JS or CSS for a project — use **building-blocks**.

This skill covers the *content* side, not the *code* side.

• Universal Editor, structured-content authoring, or AEM Cloud Service

(Java / OSGi / JCR). Out of scope.

Related Skills

• **da-auth** — Obtain the IMS token needed for every `admin.da.live`

and `admin.hlx.page` call. Invoke before any operation in this skill that needs `DA_TOKEN`.

• **generate-import-html** — Generates DA-compliant HTML for imported

pages; this skill is the rule reference for what that HTML must look like.

• **page-import** — Orchestrates full page imports into canonical

EDS block format. Reads this skill for the DA-side rules.

• **snowflake** — Static-to-EDS overlay conversion. Loads this skill

alongside its own methodology for DA HTML and admin API rules.

Minimal upload example

The most common operation — upload an HTML document to DA. Shows the non-obvious rules in one place: multipart/form-data body, field name `data`, blob with `text/html` type, Bearer IMS token, then a separate preview call to make the page reachable at `aem.page`. See [references/platform.md](./references/platform.md) for the full contract and [references/html-content.md](./references/html-content.md) for what the HTML payload must look like.

# Use $DA_TOKEN from the da-auth skill, or read a cached token file directly.
# See platform.md §3 for the cache locations the various Adobe DA tools use.
TOKEN="${DA_TOKEN:?invoke the da-auth skill to obtain a DA admin token}"

# 1. Upload HTML — note multipart with field name "data" (other names silently fail)
curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -F "data=@./page.html;type=text/html" \
  "https://admin.da.live/source/{org}/{repo}/path/to/page.html"

# 2. Trigger preview — required separate step, path WITHOUT .html extension
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  "https://admin.hlx.page/preview/{org}/{repo}/main/path/to/page"

# 3. Optional: publish to aem.live
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  "https://admin.hlx.page/live/{org}/{repo}/main/path/to/page"

Image binaries upload the same way (PUT to `admin.da.live/source/...`) but do NOT need their own preview/publish call — they're served directly from `content.da.live` once uploaded. They DO get pulled into Media Bus (content-addressed, with responsive variants) when a *document* that references them is previewed — see [references/media.md §2](./references/media.md) for the asset lifecycle.

The 11 silent-failure rules

These rules, if violated, produce broken content without any error from DA, the pipeline, or the renderer. Memorize them; verify them in generated output before upload.

1. **DA HTML is a body fragment.** No `<!DOCTYPE>`, no `<html>`, no `<head>`, no `<script>`, no `<style>`, no inline `style=` attributes. The pipeline injects head/scripts/styles from Code Bus at delivery. → [html-content.md §1](./references/html-content.md)

2. **Block class encodes block identity (canonical div form).** The outermost `<div>` carries `class="<block-name> [<variant>…]"`. The first class token is the block name and resolves to `/blocks/<name>/<name>.{js,css}`. For the accepted table-form alternate, the header is `<tr><td colspan="N">Name</td></tr>` where `N` matches the cell count of the widest content row; single-column blocks may omit `colspan`. Misshapen blocks (missing div class, multi-column table missing `colspan`, empty header cell) render as plain HTML without block JS or CSS. → [html-content.md §3](./references/html-content.md)

3. **Block names use alphanumeric + single hyphens only.** No underscores, no double dashes, no digit-first names. Variant