Adobe Experience Manager

https://www.aem.live/llms.txt
Admin
Adobe Experience Manager Edge Delivery Services enables content creators and developers to build...
Tokens:76,045
Snippets:727
Trust Score:7.8
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install AEM CLI and start local development

Source: https://www.aem.live/developer/tutorial

Install the AEM CLI globally and clone your repository, then start the local development environment with 'aem up'. The local site opens at http://localhost:3000/.

```bash
npm install -g @adobe/aem-cli
git clone https://github.com/<owner>/<repo>
```

```bash
cd <repo>
aem up
```

--------------------------------

### Example app role assignment request

Source: https://www.aem.live/docs/setup-customer-sharepoint

Example request to assign the Sites.Selected application role to the managed identity using concrete IDs from the previous steps.

```http
https://graph.microsoft.com/v1.0/servicePrincipals/6761ada0-733b-4a02-98b2-3db970834fe0/appRoleAssignedTo
Content-type: application/json
{
    "principalId": "6761ada0-733b-4a02-98b2-3db970834fe0",
    "resourceId": "5159db96-7193-414e-9730-b1d1e4448443",
    "appRoleId": "883ea226-0bf2-4a8f-9f9d-92c9162a727d"
}
```

--------------------------------

### Install aem CLI globally with npm

Source: https://www.aem.live/developer/cli-reference

Installs the @adobe/aem-cli package globally using npm.

```bash
$ npm install -g @adobe/aem-cli
```

--------------------------------

### Create library.html for sidekick library setup

Source: https://www.aem.live/docs/sidekick-library

Create this file as `tools/sidekick/library.html` to load and configure the sidekick library. It loads the library script from `https://www.aem.live/tools/sidekick/library/index.js` and creates a custom `sidekick-library` element with a `config` object that must include the `base` parameter pointing to the library JSON.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0, viewport-fit=cover"
    />
    <meta name="Description" content="AEM Sidekick Library" />
    <meta name="robots" content="noindex" />
    <base href="/" />

    <style>
      html,
      body {
        margin: 0;
        padding: 0;
        font-family: sans-serif;
        background-color: #ededed;
        height: 100%;
      }
      
      helix-sidekick { display: none }
    </style>
    <title>Sidekick Library</title>
  </head>

  <body>
    <script
      type="module"
      src="https://www.aem.live/tools/sidekick/library/index.js"
    ></script>
    <script>
      const library = document.createElement('sidekick-library')
      library.config = {
        base: '/tools/sidekick/library.json',
      }

      document.body.prepend(library)
    </script>
  </body>
</html>
```

--------------------------------

### Install Edge Delivery Services skills via GitHub CLI, Claude Code, or Codex

Source: https://www.aem.live/developer/ai-coding-agents

Install all Edge Delivery Services skills using GitHub CLI, Claude Code, or Codex. The commands add the adobe/skills plugin marketplace and install the aem-edge-delivery-services plugin. For Codex, after adding the marketplace, use the /plugins command in the CLI to search and install the plugin.

```shell
  # GitHub CLI
  $ gh extension install ai-ecoverse/gh-upskill
  $ gh upskill adobe/skills --skills-path plugins/aem/edge-delivery-services --all

  # Claude Code
  /plugin marketplace add adobe/skills
  /plugin install aem-edge-delivery-services@adobe-skills

  # Codex
  $ codex plugin marketplace add adobe/skills
  # then in Codex CLI:
  /plugins   # → search "aem-edge-delivery-services" → Install plugin
```

--------------------------------

### Example robots.txt content

Source: https://www.aem.live/docs/go-live-checklist

A good example of a robots.txt file that allows all crawlers and points to the sitemap. Note that aem.page and aem.live are kept hidden from crawlers intentionally, and a Disallow does not prevent indexing but can affect crawler budget and noindex removal.

```text
User-agent: *
Allow: /

Sitemap: https://<your-domain>/sitemap.xml
```

--------------------------------

### Add the library plugin to the sidekick config via curl

Source: https://www.aem.live/docs/sidekick-library

Posts a sidekick config to the admin service with a plugin that loads the library. The 'url' property must point to the library.html file. If a sidekick config already exists, GET it first and add the plugin to avoid overwriting.

```bash
curl -X POST https://admin.hlx.page/config/{org}/sites/{site}/sidekick.json \
  -H 'content-type: application/json' \
  -H 'x-auth-token: {your-auth-token}' \
  --data '{
    "project": "Example",
    "plugins": [{
      "id": "library",
      "title": "Library",
      "environments": ["edit"],
      "url": "/tools/sidekick/library.html",
      "includePaths": ["**.docx**"]
    }]
  }'
```

--------------------------------

### Example sitemap entry with hreflang alternates

Source: https://www.aem.live/developer/sitemap

Shows the resulting XML entry in /sitemap-en.xml when two pages share a common suffix across languages.

```xml
<url>
  <loc>https://wwww.mysite.com/welcome</loc>
  <xhtml:link rel="alternate" hreflang="en" href="https://wwww.mysite.com/welcome"/>
  <xhtml:link rel="alternate" hreflang="fr" href="https://wwww.mysite.com/fr/welcome"/>
</url>

```

--------------------------------

### Single Sheet JSON Format Example

Source: https://www.aem.live/developer/spreadsheets

Example of the JSON output for a single sheet spreadsheet, delivered at /redirects.json. Shows the structure with total, offset, limit, columns, data, and :type properties.

```json
{
  "total": 4,
  "offset": 0,
  "limit": 4,
  "columns": ["Source", "Destination"],
  "data": [
    {
      "Source": "/sidekick-extension",
      "Destination": "https://chromewebstore.google.com/detail/aem-sidekick/igkmdomcgoebiipaifhmpfjhbjccggml"
    },
    {
      "Source": "/github-bot",
      "Destination": "https://github.com/apps/helix-bot"
    },
    {
      "Source": "/install-github-bot",
      "Destination": "https://github.com/apps/helix-bot/installations/new"
    },
    {
      "Source": "/tutorial",
      "Destination": "/developer/tutorial"
    }
  ],
  ":type": "sheet"
}
```

--------------------------------

### Debug index configuration with aem up --print-index

Source: https://www.aem.live/developer/indexing

Run this AEM CLI command to print the index record whenever you change your query configuration. This helps in finding the correct CSS selectors. Requires the AEM CLI to be installed.

```bash
$ aem up --print-index
```

--------------------------------

### Example window.location object when running in the library

Source: https://www.aem.live/docs/sidekick-library

Shows the values of window.location properties when the block is loaded in an iframe using srcdoc. The href is 'about:srcdoc', origin is 'null', and other properties are empty or 'srcdoc'.

```json
{
  "host": "",
  "hostname": "",
  "href": "about:srcdoc"
  "origin": "null"
  "pathname": "srcdoc"
  "port": ""
  "protocol": "about:"
}
```

--------------------------------

### Find SharePoint Site ID and Set Permissions via Microsoft Graph

Source: https://www.aem.live/docs/setup-customer-sharepoint

To add permissions to a SharePoint site, first find its SiteId by calling GET on the site path. Then use that Id in the POST permissions request to grant write access to the AEM Content Integration application. The GET example shows the response field 'id' that contains the site ID. Ensure you have Site Admin permissions and consent for Sites scopes, otherwise you may get an 'Access Denied' error.

```http
GET https://graph.microsoft.com/v1.0/sites/{host-name}:/{server-relative-path}
```

```http
GET https://graph.microsoft.com/v1.0/sites/adobeenterprisesupportaem.sharepoint.com:/sites/hlx-test-project

{
...
    "id": "adobeenterprisesupportaem.sharepoint.com,03cc3587-0e4d-405e-b06c-ffb0a622b7ac,5fbc1df5-640c-4780-8b59-809e3193c043",
...
}
```

```http
POST https://graph.microsoft.com/v1.0/sites/adobeenterprisesupportaem.sharepoint.com,03cc3587-0e4d-405e-b06c-ffb0a622b7ac,5fbc1df5-640c-4780-8b59-809e3193c043/permissions
Content-type: application/json

{
    "roles": [
        "write"
    ],
    "grantedToIdentities": [
        {
            "application": {
                "id": "83ab2922-5f11-4e4d-96f3-d1e0ff152856",
                "displayName": "AEM Content Integration"
            }
        }
    ]
}
```

--------------------------------

### Create AEM Content Integration service principal via PowerShell

Source: https://www.aem.live/docs/setup-customer-sharepoint

Uses the Microsoft Graph PowerShell SDK to create the service principal. Requires the Application.ReadWrite.All scope and the same appId and tag as the REST example.

```powershell
PS> connect-MgGraph -Scopes "Application.ReadWrite.All"
PS> New-MgServicePrincipal -AppId 83ab2922-5f11-4e4d-96f3-d1e0ff152856 -Tags WindowsAzureActiveDirectoryIntegratedApp
```

--------------------------------

### Custom HTTP Response Headers in site configuration

Source: https://www.aem.live/docs/custom-headers

Example of specifying custom HTTP response headers in the site configuration. The URL property is a glob pattern; `*` can be used as a prefix or suffix, and `**` for deep path matching. Headers apply to both preview and live content; changes to content purge caches automatically, while code resource changes require a code sync.

```json
{
  "/fragments/**": [
    {
      "key": "access-control-allow-origin",
      "value": "https://www.example.com"
    }
  ]
}
```

--------------------------------

### GET /{path}.json

Source: https://www.aem.live/developer/spreadsheets

Documentation for retrieving spreadsheet data via AEM's JSON delivery endpoint, including multi-sheet format and query parameters.

```APIDOC
## GET /{path}.json?limit={limit}&offset={offset}

### Description
Retrieves spreadsheet data in JSON format. Supports pagination via `limit` and `offset` query parameters, and sheet selection via the `sheet` parameter.

### Method
GET

### Endpoint
`/{path}.json`

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of rows to return. If not specified, defaults to 1000.
- **offset** (integer) - Optional - Number of rows to skip before starting to return data.
- **sheet** (string) - Optional - Specifies one or more sheets to return. Can be repeated to select multiple sheets. Example: `?sheet=jobs` returns the sheet named `shared-jobs`; `?sheet=jobs&sheet=articles` returns both sheets in multi-sheet format.

### Response
#### Success Response (200)
- **:type** (string) - The JSON data format included in the payload. Possible values: `multi-sheet` or single sheet format.
- **:names** (array of strings) - Present in multi-sheet format. Contains the names of the contained sheets.
- **{sheetName}** (object) - For each sheet name in `:names`, a property containing the sheet data in single sheet format.

#### Response Example
```json
{
  ":names": [
    "first",
    "second"
  ],
  ":type": "multi-sheet",
  "first": {
    "total": 0,
    "offset": 0,
    "limit": 0,
    "data": [],
    "columns": []
  },
  "second": {
    "total": 0,
    "offset": 0,
    "limit": 0,
    "data": [],
    "columns": []
  }
}
```
```

--------------------------------

### Multi-Sheet JSON Payload Example

Source: https://www.aem.live/developer/spreadsheets

Example payload returned when multiple sheets with 'shared-' prefixes exist but none is named 'shared-default'. The ':type' property indicates the JSON format, ':names' lists the sheet names, and each sheet name maps to its data in single-sheet format.

```json
{
  ":names": [
    "first",
    "second"
  ],
  ":type": "multi-sheet",
  "first": {
    "total": 0,
    "offset": 0,
    "limit": 0,
    "data": [],
    "columns": []
  },
  "second": {
    "total": 0,
    "offset": 0,
    "limit": 0,
    "data": [],
    "columns": []
  }
}
```

--------------------------------

### decorate(container, data, query, context)

Source: https://www.aem.live/docs/sidekick-library

The decorate() function is the main entry point for a sidekick library plugin. It is called when a user tries to load the plugin and must be exported from the plugin.

```APIDOC
## decorate(container, data, query, context)

### Description
Called when a user tries to load the plugin. This method receives the container to render the plugin in and any data that is included in the plugins sheet.

### Method
Function (exported from plugin)

### Parameters
- **container** (HTMLElement) - Required - The container to render the plugin in
- **data** (Object) - Required - The data contained in the plugin sheet
- **query** (String) - Optional - If search is active, the current search query
- **context** (Object) - Optional - Contains any properties set when the plugin was registered

### Request Example
```javascript
/**
 * Called when a user tries to load the plugin
 * @param {HTMLElement} container The container to render the plugin in
 * @param {Object} data The data contained in the plugin sheet
 * @param {String} query If search is active, the current search query
 * @param {Object} context contains any properties set when the plugin was registered
 */
export async function decorate(container, data, query, context) {
  // Render your plugin
}
```

### Response
No return value specified.
```

--------------------------------

### Show aem CLI help

Source: https://www.aem.live/developer/cli-reference

Displays the help information for the aem CLI, listing available commands and options.

```bash
$ aem --help
```

--------------------------------

### Basic sidekick configuration

Source: https://www.aem.live/developer/sidekick-development

Base sidekick configuration object with a project name and an empty plugins array. Add this to your site configuration to customize the sidekick.

```json
{
  "project": "My project",
  "plugins": []
}
```

--------------------------------

### Configure additional metadata sources via admin API

Source: https://www.aem.live/docs/bulk-metadata

POST to the admin API to configure multiple metadata files. The order of the array determines application order; duplicate properties can be overwritten by subsequent sources but never deleted.

```bash
curl -X POST https://admin.hlx.page/config/{org}/sites/{site}/metadata.json \
  -H 'content-type: application/json' \
  -H 'x-auth-token: {your-auth-token}' \
  --data '{
    "source": [
        "/metadata.json",
        "/metadata-2nd.json",
        "/metadata-seo.json"
    ]
}'
```

--------------------------------

### aem CLI help output

Source: https://www.aem.live/developer/cli-reference

The output of 'aem --help' showing usage, commands, and options.

```text
Usage: aem <command> [options]

Commands:
  aem up       Run a AEM development server
  aem import   Run the AEM import server
  aem content  Manage AEM content from da.live



Options:
  --version                Show version number                         [boolean]
  --log-file, --logFile    Log file (use "-" for stdout)  [array] [default: "-"]
  --log-level, --logLevel  Log level
  [string] [choices: "silly", "debug", "verbose", "info", "warn", "error"] [default: "info"]
  --help                   Show help                                   [boolean]

use <command> --help to get command specific details.

for more information, find our manual at https://github.com/adobe/helix-cli
```

--------------------------------

### GET /redirects.json

Source: https://www.aem.live/developer/spreadsheets

Retrieves the JSON representation of a spreadsheet. The response contains the sheet data in a structured JSON format, including metadata such as total entries, offset, and limit.

```APIDOC
## GET /redirects.json

### Description
Retrieves the JSON representation of a spreadsheet. The response contains the sheet data in a structured JSON format, including metadata such as total entries, offset, and limit.

### Method
GET

### Endpoint
`/redirects.json`

### Parameters
#### Query Parameters
- **sheet** (string) - Optional - Specifies the sheet name to retrieve. The sheet named `shared-{name}` will be delivered as a single sheet.
- **limit** (integer) - Optional - Limits the number of entries returned in the response.
- **offset** (integer) - Optional - Specifies the offset for pagination.

### Response
#### Success Response (200)
- **total** (integer) - The total number of entries available.
- **offset** (integer) - The value of the offset query parameter.
- **limit** (integer) - The value of the limit query parameter.
- **columns** (array of strings) - The sheet header names.
- **data** (array of objects) - The sheet data as an array of JSON objects.
- **:type** (string) - The JSON data format included in the payload.

#### Response Example
```json
{
  "total": 4,
  "offset": 0,
  "limit": 4,
  "columns": ["Source", "Destination"],
  "data": [
    {
      "Source": "/sidekick-extension",
      "Destination": "https://chromewebstore.google.com/detail/aem-sidekick/igkmdomcgoebiipaifhmpfjhbjccggml"
    },
    {
      "Source": "/github-bot",
      "Destination": "https://github.com/apps/helix-bot"
    },
    {
      "Source": "/install-github-bot",
      "Destination": "https://github.com/apps/helix-bot/installations/new"
    },
    {
      "Source": "/tutorial",
      "Destination": "/developer/tutorial"
    }
  ],
  ":type": "sheet"
}
```
```

--------------------------------

### AEM Content Add Usage

Source: https://www.aem.live/developer/cli-reference

Syntax for staging files using the content add command.

```bash
$ aem content add <path> [<path> ...]
```

--------------------------------

### Simple sitemap with origin

Source: https://www.aem.live/developer/sitemap

Specifies an optional origin (must include protocol) when cdn.prod.host is not defined or a different host is needed for sitemap URLs.

```yaml
 sitemaps:
   example:
     origin: https://www.mysite.com
     source: /query-index.json
     destination: /sitemap-en.xml
     lastmod: YYYY-MM-DD

```

--------------------------------

### Omitting metadata values with empty string

Source: https://www.aem.live/docs/bulk-metadata

Use an empty string value in the bulk metadata sheet to remove a metadata element or set an attribute to empty for a specific path. The example removes the canonical link from all pages unless overridden.

```text
URL          Canonical
/**          ""
```

--------------------------------

### Create a container plugin and add a plugin to it

Source: https://www.aem.live/developer/sidekick-development

Defines a container plugin with 'isContainer' and adds a plugin to it using 'containerId'. The container toggles a dropdown and cannot have its own URL or event action.

```json
{
  "plugins": [
    {
      "id": "tools",
      "title": "Tools",
      "isContainer": true
    },
    {
      "id": "foo",
      "containerId": "tools",
      "title": "Foo",
      "event": "foo"
    }
  ]
}
```

--------------------------------

### Configure custom viewports (full form)

Source: https://www.aem.live/docs/sidekick-library

Sets custom viewport sizes using a full configuration object with width, label, icon, and default properties. Overrides the default viewport sizes.

```javascript
const library = document.createElement('sidekick-library')
library.config = {
  base: '/tools/sidekick/library.json',
  plugins: {
    blocks: {
      viewPorts: [
        {
          width: '599px',
          label: 'Small',
          icon: 'device-phone',
        },
        {
          width: '899px',
          label: 'Medium',
          icon: 'device-tablet',
        },
        {
          width: '100%',
          label: 'Large',
          icon: 'device-desktop',
          default: true,
        },
      ],
    }
  }
}
```

--------------------------------

### Create a standard palette plugin with isPalette

Source: https://www.aem.live/developer/sidekick-development

Configures a URL-based plugin to open in a floating palette instead of a new tab. The 'isPalette' boolean is set to true and the plugin's URL is specified.

```json
{
  "plugins": [
    {
      "id": "foo",
      "title": "Foo",
      "url": "/tools/sidekick/foo-palette.html",
      "isPalette": true
    }
  ]
}
```

--------------------------------

### Simple sitemap configuration

Source: https://www.aem.live/developer/sitemap

Basic helix-sitemap.yaml defining a single sitemap with source and destination. Use when you have one index containing all pages for the sitemap.

```yaml
 sitemaps:
   example:
     source: /query-index.json
     destination: /sitemap-en.xml

```

--------------------------------

### Aggregate multiple indexes into one sitemap

Source: https://www.aem.live/developer/sitemap

Shows how to aggregate separate indexes into a single sitemap by using the same destination for multiple languages. Useful when there is a limit on sitemaps per site.

```yaml
sitemaps:
   example:
     lastmod: YYYY-MM-DD
     languages:
       dk:
         source: /dk/query-index.json
         destination: /sitemap.xml
         hreflang: dk
         alternate: /dk/{path}
       no:
         source: /no/query-index.json
         destination: /sitemap.xml
         hreflang: no
         alternate: /no/{path}
```

--------------------------------

### Listening for Sidekick Events

Source: https://www.aem.live/developer/sidekick-development

Use this snippet to react to sidekick events in your project code, such as in /scripts/scripts.js. Replace 'foo' with the event name. It handles both the case where the sidekick is already loaded and when it loads later, using the 'sidekick-ready' event.

```javascript
const doFoo = ({ detail: payload }) => {
  console.log('something happened', payload);
  // your custom code goes here
};

const sk = document.querySelector('aem-sidekick');
if (sk) {
  // sidekick already loaded
  sk.addEventListener('foo', doFoo);
} else {
  // wait for sidekick to be loaded
  document.addEventListener('sidekick-ready', () => {
    // sidekick now loaded
    document.querySelector('aem-sidekick')
      .addEventListener('foo', doFoo);
  }, { once: true });
}
```

--------------------------------

### Define a custom tags plugin in the sidekick library config

Source: https://www.aem.live/docs/sidekick-library

Sets the library config with a custom plugin named 'tags'. The plugin object's keys must match the plugin name; additional properties like 'foo' are passed to the plugin via the context argument of the decorate method.

```javascript
const library = document.createElement('sidekick-library')
library.config = {
  base: '/tools/sidekick/library.json',
  plugins: {
    tags: {
      src: '/tools/sidekick/plugins/tags/tags.js',
      foo: 'bar'
    }
  }
}
```

--------------------------------

### Configure custom viewports (short form)

Source: https://www.aem.live/docs/sidekick-library

Sets custom viewport sizes using a simplified array format with width values in pixels. Overrides the default viewport sizes (480px mobile, 768px tablet, 100% desktop).

```javascript
const library = document.createElement('sidekick-library')
library.config = {
  base: '/tools/sidekick/library.json',
  plugins: {
    blocks: {
      viewPorts: [600, 900],
    }
  }
}
```

--------------------------------

### Show and hide loader with PLUGIN_EVENTS.SHOW_LOADER and HIDE_LOADER

Source: https://www.aem.live/docs/sidekick-library

Show and hide a loader in the sidekick library by dispatching PLUGIN_EVENTS.SHOW_LOADER and PLUGIN_EVENTS.HIDE_LOADER events. The ellipsis (...) indicates where the plugin's work happens between the two events.

```javascript
import { PLUGIN_EVENTS } from 'https://www.aem.live/tools/sidekick/library/events/events.js';

export async function decorate(container, data, query) {
  // Show loader
  container.dispatchEvent(new CustomEvent(PLUGIN_EVENTS.SHOW_LOADER))
  ...
  // Hide loader
  container.dispatchEvent(new CustomEvent(PLUGIN_EVENTS.HIDE_LOADER))
}
```

--------------------------------

### Include external sitemap as input

Source: https://www.aem.live/developer/sitemap

Shows how to include sitemaps from other language trees by specifying an XML path as source. AEM determines alternates for English URLs by deconstructing French counterparts using the 'alternate' definition.

```yaml
sitemaps:
   example:
     lastmod: YYYY-MM-DD
     languages:
       en:
         source: /en/query-index.json
         destination: /sitemaps/sitemap-en.xml
         hreflang: en
       fr:
         source: https://www.mysite.com/legacy/sitemap-fr.xml
         destination: /sitemaps/sitemap-fr.xml
         hreflang: fr
         alternate: /fr/{path}
```

--------------------------------

### Add extension to all locations

Source: https://www.aem.live/developer/sitemap

Shows how to add an extension (e.g., .html) to all locations in a sitemap using the 'extension' property. Can be applied to all languages or individual languages.

```yaml
sitemaps:
   example:
     lastmod: YYYY-MM-DD
     extension: .html
     languages:
       en:
         source: /en/query-index.json
         destination: /en/sitemap.xml
         hreflang: en
       fr:
         source: /fr/query-index.json
         destination: /fr/sitemap.xml
         hreflang: fr
         alternate: /fr/{path}
```

--------------------------------

### aem content clone

Source: https://www.aem.live/developer/cli-reference

Clones da.live content into a local content/ folder.

```APIDOC
## aem content clone

### Description
Downloads da.live sources into `./content/`, initializes a git repository with a baseline commit, writes a `.da-config.json` (org, site, root path) inside `content/`, and records initial sync state.

### Method
CLI command

### Endpoint
`aem content clone`

### Parameters
#### Options
- `--path` (string) - Optional - da.live folder to clone (e.g. `/ca/fr_ca`). Omit only when using `--all`.
- `--all` (boolean) - Optional - Clone the entire site content (large). Use instead of `--path`.
- `--force` (boolean) - Optional - Overwrite an existing local content folder.
- `--yes` (boolean) - Optional - Skip the confirmation prompt. Required in non-interactive environments (e.g. CI) when the clone has more than 10,000 files.
- `--token` (string) - Optional - IMS token (see Authentication).
- `--org` (string) - Optional - The da.live `org` to clone from.
- `--site` (string) - Optional - The da.live `site` to clone from.

### Request Example
```
aem content clone --path /ca/fr_ca
```

### Response
#### Success Response
- No explicit response body documented.

#### Response Example
No explicit response example documented.
```

--------------------------------

### Deny everything, allow few - runtime_blocked_hosts and runtime_allowed_hosts

Source: https://www.aem.live/docs/sidekick-security

Defines a Chrome enterprise policy that blocks the Sidekick extension from all URLs except those matching the allowed patterns. Uses both 'runtime_blocked_hosts' and 'runtime_allowed_hosts' settings. The allowed hosts include admin.hlx.page, api.aem.live, rum.hlx.page, localhost:3000, sharepoint.com, and aem.* patterns.

```json
{
  "igkmdomcgoebiipaifhmpfjhbjccggml": {
    "runtime_blocked_hosts": ["http*://*/*"],
    "runtime_allowed_hosts": [
      "https://admin.hlx.page/*",
      "https://api.aem.live/*",
      "https://rum.hlx.page/*",
      "http://localhost:3000/*",
      "https://*.sharepoint.com/*",
      "https://*--project--example.aem.*/*"
    ]
  }
}
```

--------------------------------

### Multiple sitemaps with hreflang

Source: https://www.aem.live/developer/sitemap

Defines multiple sitemaps per language with hreflang and alternate references. Assumes one-to-one mapping between indexes and sitemap XML files.

```yaml
 sitemaps:
   example:
     lastmod: YYYY-MM-DD
     languages:
       en:
         source: /en/query-index.json
         destination: /sitemap-en.xml
         hreflang: en
       fr:
         source: /fr/query-index.json
         destination: /sitemap-fr.xml
         hreflang: fr
         alternate: /fr/{path}

```

--------------------------------

### Create VCL snippets for miss and pass subroutines

Source: https://www.aem.live/docs/byo-cdn-fastly-setup

VCL snippet for the `miss` and `pass` subroutines. Sets `X-BYO-CDN-Type` to `fastly` and enables push invalidation with `X-Push-Invalidation: enabled`.

```vcl
set bereq.http.X-BYO-CDN-Type = "fastly";
set bereq.http.X-Push-Invalidation = "enabled";
```

--------------------------------

### Create service principal using PowerShell

Source: https://www.aem.live/docs/setup-customer-sharepoint

Creates a service principal for the AEM Content Integration Registration application using PowerShell. The command connects to Microsoft Graph with the Application.ReadWrite.All scope and adds the WindowsAzureActiveDirectoryIntegratedApp tag. Requires the Microsoft.Graph PowerShell module.

```powershell
PS> connect-MgGraph -Scopes "Application.ReadWrite.All"
PS> New-MgServicePrincipal -AppId e34c45c4-0919-43e1-9436-448ad8e81552 -Tags WindowsAzureActiveDirectoryIntegratedApp
```

--------------------------------

### Create VCL snippet for recv subroutine

Source: https://www.aem.live/docs/byo-cdn-fastly-setup

VCL snippet for the `recv` subroutine. It remembers the query string in `X-QS` and strips it from the request URL for non-media, non-image, non-JSON, and non-`.auth` paths.

```vcl
if (fastly.ff.visits_this_service == 0) {
  # edge delivery node
  if (req.url.qs != "") {
    # remember query string
    set req.http.X-QS = req.url.qs;

    if (req.url.path !~ "/media_[0-9a-f]{40,}[/a-zA-Z0-9_-]*\.[0-9a-z]+$" 
      && req.url.ext !~ "(?i)^(gif|png|jpe?g|webp)$"
      && req.url.ext != "json"
      && req.url.path != "/.auth") {
      # strip query string from request url
      set req.url = req.url.path;
    }
  }
}
```

--------------------------------

### Configure custom edit URL with editUrlPattern

Source: https://www.aem.live/developer/sidekick-development

Configures a custom editing environment for projects not using SharePoint or Google Drive. 'editUrlLabel' sets the visible label, and 'editUrlPattern' defines the URL pattern with placeholders like '{{contentSourceUrl}}' and '{{pathname}}'.

```json
{
  "editUrlLabel": "Your Editor",
  "editUrlPattern": "{{contentSourceUrl}}{{pathname}}?cmd=open"
}
```

--------------------------------

### HTML viewer file for special view

Source: https://www.aem.live/developer/sidekick-development

HTML file to place at the path specified by 'viewer' in the special view configuration. It includes a CSS file and a JS file with custom logic, both in the same directory.

```html
<html>
<head>
  <title>Custom JSON Viewer</title>
  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" href="./custom-json-viewer.css">
  <!-- add your custom code -->
  <script src="./custom-json-viewer.js"></script>
</head>
  <body>
  </body>
</html>
```

--------------------------------

### decorate() function

Source: https://www.aem.live/docs/sidekick-library

Exported function called when a user loads the plugin. Receives the container, data, query, and context parameters.

```javascript
/**
 * Called when a user tries to load the plugin
 * @param {HTMLElement} container The container to render the plugin in
 * @param {Object} data The data contained in the plugin sheet
 * @param {String} query If search is active, the current search query
 * @param {Object} context contains any properties set when the plugin was registered
 */
export async function decorate(container, data, query, context) {
  // Render your plugin
}
```

--------------------------------

### URL-based plugin configuration

Source: https://www.aem.live/developer/sidekick-development

Defines a URL-based plugin that opens a new tab when clicked. The url property specifies the page to open.

```json
{
  "plugins": [
    {
      "id": "foo",
      "title": "Foo",
      "url": "/tools/sidekick/foo.html"
    }
  ]
}
```

--------------------------------

### AEM Content Diff Options

Source: https://www.aem.live/developer/cli-reference

Options for the content diff command, specifically the token flag for authentication.

```bash
--token
 IMS token (see Authentication).
```

--------------------------------

### Allow everything, deny few - runtime_blocked_hosts

Source: https://www.aem.live/docs/sidekick-security

Defines a Chrome enterprise policy that blocks the Sidekick extension from interacting with specific URLs. The extension ID 'igkmdomcgoebiipaifhmpfjhbjccggml' is used with the 'runtime_blocked_hosts' setting to deny access to the listed patterns.

```json
{
  "igkmdomcgoebiipaifhmpfjhbjccggml": {
    "runtime_blocked_hosts": [
      "https://intranet.example.com/*",
      "https://extranet.example.com/*"
    ]
  }
}
```

--------------------------------

### Customize default publish plugin with excludePaths

Source: https://www.aem.live/developer/sidekick-development

Customizes the default publish plugin to appear only in the preview environment and only when the current resource path does not contain a 'drafts' segment. Uses the 'excludePaths' and 'environments' properties.

```json
{
  "plugins": [
    {
      "id": "publish",
      "excludePaths": ["**/drafts/**"],
      "environments": ["preview"]
    }
  ]
}
```

--------------------------------

### Sitemap with default language

Source: https://www.aem.live/developer/sitemap

Configuration specifying a default language for multi-language sitemaps, with hreflang and alternate entries.

```yaml
 sitemaps:
   example:
     default: en
     lastmod: YYYY-MM-DD
     languages:
       en:
         source: /en/query-index.json
         destination: /sitemap-en.xml
         hreflang: en
       fr:
         source: /fr/query-index.json
         destination: /sitemap-fr.xml
         hreflang: fr
         alternate: /fr/{path}

```

--------------------------------

### aem content diff [path]

Source: https://www.aem.live/developer/cli-reference

Shows the diff between local and remote content.

```APIDOC
## aem content diff [path]

### Description
Shows the diff between your local working tree and the remote on da.live. Pass an optional path (e.g. /blog/post.html) to limit the diff to a single file; omit it to diff all modified files.

### Method
CLI command

### Endpoint
`aem content diff [path]`

### Parameters
#### Path Parameters
- `path` (string) - Optional - Path to a single file to diff (e.g. /blog/post.html).

#### Options
- `--token` (string) - Optional - IMS token (see Authentication).

### Request Example
```
aem content diff /blog/post.html
```

### Response
#### Success Response
- No explicit response body documented.

#### Response Example
No explicit response example documented.
```

--------------------------------

### Create deliver snippet to preserve query string in redirects

Source: https://www.aem.live/docs/byo-cdn-fastly-setup

VCL snippet for the `deliver` subroutine. Preserves the request query string in redirect locations for 3xx responses when the location header lacks a query string.

```vcl
if (fastly.ff.visits_this_service == 0) {
  # on edge delivery node
  if (
    http_status_matches(resp.status, "301,302,303,307,308")
    && req.http.X-QS
    && resp.http.location
    && resp.http.location !~ "\?.*\z"
  ) {
    # preserve request query string in redirect location
    set resp.http.location = resp.http.location "?" req.http.X-QS;
  }
}
```

--------------------------------

### Add a badge plugin with isBadge

Source: https://www.aem.live/developer/sidekick-development

Adds a non-clickable 'Stage' badge to the sidekick toolbar in the preview environment. The 'isBadge' property renders the plugin as a badge, and 'badgeVariant' can optionally set its color scheme.

```json
{
  "plugins": [
    {
      "id": "stage",
      "title": "Stage",
      "isBadge": true,
      "environments" ["preview"]
    }
  ]
}
```

--------------------------------

### getOrigin and getHref helper functions for scripts.js

Source: https://www.aem.live/docs/sidekick-library

Recommended functions to add to scripts.js and import into your block code. getOrigin returns the true origin, and getHref returns the true href, handling the srcdoc iframe case by using the parent location and the 'path' query parameter.

```javascript
/**
 * Returns the true origin of the current page in the browser.
 * If the page is running in a iframe with srcdoc, the ancestor origin is returned.
 * @returns {String} The true origin
 */
export function getOrigin() {
  const { location } = window;
  return location.href === 'about:srcdoc' ? window.parent.location.origin : location.origin;
}

/**
 * Returns the true of the current page in the browser.mac
 * If the page is running in a iframe with srcdoc,
 * the ancestor origin + the path query param is returned.
 * @returns {String} The href of the current page or the href of the block running in the library
 */
export function getHref() {
  if (window.location.href !== 'about:srcdoc') return window.location.href;

  const { location: parentLocation } = window.parent;
  const urlParams = new URLSearchParams(parentLocation.search);
  return `${parentLocation.origin}${urlParams.get('path')}`;
}
```

--------------------------------

### Multiple hreflangs for one subtree

Source: https://www.aem.live/developer/sitemap

Shows how to map multiple hreflangs to a single language subtree by specifying an array of languages in the 'hreflang' property. Each page appears once but has multiple alternate hreflangs.

```xml
<url>
 <loc>https://myhost/la/page</loc>
 <xhtml:link rel="alternate" hreflang="es-VE" href="https://myhost/la/page"/>
 <xhtml:link rel="alternate" hreflang="es-SV" href="https://myhost/la/page"/>
 <xhtml:link rel="alternate" hreflang="es-PA" href="https://myhost/la/page"/>
</url>
```

```yaml
sitemaps:
   example:
     lastmod: YYYY-MM-DD
     languages:
       la:
         source: /la/query-index.json
         destination: /sitemap-la.xml
         hreflang:
           - es-VE
           - es-SV
           - es-PA
```

--------------------------------

### Simple sitemap with lastmod

Source: https://www.aem.live/developer/sitemap

Adds a lastmod property with format YYYY-MM-DD to include last modification dates in sitemap URLs.

```yaml
 sitemaps:
   example:
     source: /query-index.json
     destination: /sitemap-en.xml
     lastmod: YYYY-MM-DD

```

--------------------------------

### Create final deliver snippet to unset Age and X-Robots-Tag

Source: https://www.aem.live/docs/byo-cdn-fastly-setup

Final VCL snippet for the `deliver` subroutine. Removes the `Age` header and the `X-Robots-Tag` header for non-plain HTML responses.

```vcl
unset resp.http.Age;

if (req.url.path !~ "\.plain\.html$") {
  unset resp.http.X-Robots-Tag;
}
```

--------------------------------

### AEM Content Workflow Commands

Source: https://www.aem.live/developer/cli-reference

A typical workflow for managing content using the AEM CLI, from cloning remote content to pushing local edits.

```bash
$ aem content clone            # fetch remote content into ./content
$ # edit files under ./content
$ aem content status           # see what changed
$ aem content diff             # compare local vs remote
$ aem content add <path>       # stage changes
$ aem content commit -m "..."  # commit staged changes
$ aem content push             # upload to da.live
```

--------------------------------

### Configure popover width and height with popoverRect

Source: https://www.aem.live/developer/sidekick-development

Adds a 'popoverRect' string to a popover plugin to define its width and height.

```json
{
  "plugins": [
    {
      "id": "foo",
      "title": "Foo",
      "url": "/tools/sidekick/foo-popover.html",
      "isPopover": true,
      "popoverRect": "width:300px;height:200px;"
    }
  ]
}
```

--------------------------------

### Configure sitemap index in helix-sitemap.yaml

Source: https://www.aem.live/developer/sitemap

Configure AEM to automatically generate a sitemap index by adding an `index` property to `helix-sitemap.yaml`. Entries can be paths relative to the sitemap's origin (or `cdn.prod.host` if origin isn't set) or fully qualified URLs for sitemaps not generated by this configuration. The generated index is published at `https://<branch>--<repo>--<owner>.aem.page/sitemap-index.xml` and takes precedence over any static `sitemap-index.xml` file.

```yaml
sitemaps:
  multilang:
    origin: https://www.example.com
    languages:
      en:
        source: /en/query-index.json
        destination: /sitemap-en.xml
        hreflang: en
      fr:
        source: /fr/query-index.json
        destination: /sitemap-fr.xml
        hreflang: fr
        alternate: /fr/{path}
      la:
        source: /la/query-index.json
        destination: /sitemap-la.xml
        hreflang:
          - es-VE
          - es-SV
          - es-PA
        alternate: /la/{path}

index:
  - /sitemap-en.xml
  - /sitemap-fr.xml
  - /sitemap-la.xml
  - https://www.example.com/sitemap-other.xml
```

--------------------------------

### Configure palette size and position with paletteRect

Source: https://www.aem.live/developer/sidekick-development

Adds a 'paletteRect' string to a palette plugin to define its size and position using CSS-like properties (top, left, height, width).

```json
{
  "plugins": [
    {
      "id": "foo",
      "title": "Foo",
      "url": "/tools/sidekick/foo-palette.html",
      "isPalette": true,
      "paletteRect": "top:150px;left:7%;height:675px;width:85vw;"
    }
  ]
}
```

--------------------------------

### Create a standard popover plugin with isPopover

Source: https://www.aem.live/developer/sidekick-development

Configures a URL-based plugin to open in a popover instead of a new tab. The 'isPopover' boolean is set to true.

```json
{
  "plugins": [
    {
      "id": "foo",
      "title": "Foo",
      "url": "/tools/sidekick/foo-popover.html",
      "isPopover": true
    }
  ]
}
```

--------------------------------

### Create service principal using Microsoft Graph

Source: https://www.aem.live/docs/setup-customer-sharepoint

Creates a service principal for the AEM Content Integration Registration application using Microsoft Graph. The request includes the WindowsAzureActiveDirectoryIntegratedApp tag to make the application visible in the Azure UI. Requires appropriate permissions to create service principals.

```http
POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-type: application/json
{
    "appId": "e34c45c4-0919-43e1-9436-448ad8e81552",
    "tags": [
        "WindowsAzureActiveDirectoryIntegratedApp"
    ]
}
```

--------------------------------

### Enable publish confirmation dialog

Source: https://www.aem.live/developer/sidekick-development

Enables a confirmation dialog for the publish plugin before executing the action. This can be used as an extra precaution for critical content. Note: Publish confirmations can only be enabled for your entire site.

```json
{
  "plugins": [
    {
      "id": "publish",
      "confirm": true
    }
  ]
}
```

--------------------------------

### aem content merge [path]

Source: https://www.aem.live/developer/cli-reference

Merges remote content into local files.

```APIDOC
## aem content merge [path]

### Description
Merges remote content into local files when both sides have changed. Pass an optional path (e.g. /blog/post.html) to merge a single file; omit it to merge all modified files.

### Method
CLI command

### Endpoint
`aem content merge [path]`

### Parameters
#### Path Parameters
- `path` (string) - Optional - Path to a single file to merge (e.g. /blog/post.html).

#### Options
- `--token` (string) - Optional - IMS token (see Authentication).

### Request Example
```
aem content merge /blog/post.html
```

### Response
#### Success Response
- No explicit response body documented.

#### Response Example
No explicit response example documented.
```
Tokens:
Raw