style
content

Bring Your Own Markup

Edge Delivery Services is independent of the authoring tooling and supports multiple content sources. This means you could provide your own content source and publish the content from a repository you already have to AEM without having to migrate the content first.

The API that enables it is called Bring Your Own Markup (BYOM). It uses HTML as the standard data format.

Bring Your Own Markup is widely adopted and two of Adobe's own content sources already implement it. BYOM is generic and easy to implement; it can be used for any content source.

What format should the source bring to the table

The data format for BYOM is HTML - in fact, it is the same semantic HTML structure used by Edge Delivery Services when rendering your website.

For each page that is previewed, your BYOM service must return an HTML response. This means that the HTML must follow the semantics of sections, blocks and default content.

A very minimal example of this looks like:

<!DOCTYPE html>
<html>
  <head>
    <title>Home</title>
  </head>
  <body>
    <header></header>
    <main>
      <div>
        <div class="hero">
          <div>
            <div>
              <p>
                <picture>
                  <img loading="lazy" alt="" src="myimage.jpg">
                </picture>
              </p>
              <h1>Hello World</h1>
            </div>
          </div>
        </div>
        <p>Welcome to your website.</p>
        <div class="metadata">
          <div>
            <div>
              <p>Description</p>
            </div>
            <div>
              <p>Page Description</p>
            </div>
          </div>
        </div>
      </div>
    </main>
    <footer></footer>
  </body>
</html>

Extra elements such as span tags, data attributes, or styles are removed when content is ingested. Page metadata can be provided via the common meta tags in the HTML head or via a metadata block with the page content.

Image source URLs within the content must be accessible by Edge Delivery Services. The images will be downloaded and ingested during the preview of the page. Image source can be an absolute URL or relative to the page.

What about sheets?

Structured data in the form of spreadsheets can be provided via BOYM as well. The data is provided as a JSON. The format of the JSON has to follow the Edge Delivery Services sheet format.

Setup BYOM as primary content source

The configuration of BYOM as the primary content source is carried out as for all projects either via fstab.yaml or via the configuration service..

A file based setup will use an fstab.yaml like this:

mountpoints:
  /:
    url: "https://content-service.acme.com/data"
    type: "markup"
    suffix: ".html"

If the site is set up using the configuration service the site config can be created like this:

curl -X PUT https://admin.hlx.page/config/acme/sites/website.json \
  -H 'content-type: application/json' \
  -H 'x-auth-token: <your-auth-token>' \
  --data '{
  "version": 1,
  "code": {
    "owner": "acme",
    "repo": "website"
  },
  "content": {
    "source": {
      "url": "https://content-service.acme.com/data",
      "type": "markup",
      "suffix": ".html"
    }
  }
}'

The path of the page being published is appended to the provided BYOM source URL.

In both configuration options the "type": "markup" must be present to indicate this is a BYOM content source. "suffix": ".html" is an optional configuration, the admin service will add the suffix when requesting the content from the BYOM service URL.

Setup BYOM as content overlay

BYOM can also be used as an overlay for another content source. It does not matter whether the primary content source is SharePoint, Google Drive or BYOM. However, the overlay content source must always be BYOM. A typical use case for such a setup is, for example, the automatic publishing of product pages directly from the commerce backend.

To use the content overlay the site must use the configuration service. A file based setup via fstab.yaml is not supported.

curl -X PUT https://admin.hlx.page/config/acme/sites/website.json \
  -H 'content-type: application/json' \
  -H 'x-auth-token: <your-auth-token>' \
  --data '{
  "version": 1,
  "code": {
    "owner": "acme",
    "repo": "website"
  },
  "content": {
    "source": {
      "url": "https://acme.sharepoint.com/sites/aem/Shared%20Documents/website"
    },
    "overlay": {
      "url": "https://content-service.acme.com/data",
      "type": "markup"
    }
  }
}'