DocumentationExperience League Authoring Guide

Microsites

Last update: Fri Sep 12 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

A microsite is an HTML website that is uploaded to Experience League directly instead of through the standard authoring pipeline. Microsites are useful for displaying HTML sample files or providing tools or services not available through markdown authoring.

Examples:

Create a microsite

Before you create a microsite, talk to Bob. We’re currently moving microsites off the old system on git.corp.adobe.com and onto the new GitHub Enterprise Cloud.

  1. Create an AdobeDocs git repo that begins with microsite- (no .en suffix).

    For microsites, the repo name is NOT used in the URL.

  2. Add the HTML files and supporting CSS/JS reference files to the repo.

    Microsite git repo

  3. Log a JIRA ticket (project = UGP; component = Authoring) with a title such as “Add microsite for <x>,” and assign it to Bob Bringhurst.

    Bob will work with you to determine the microsite URL. See image below for examples.

  4. (Admin task) Specify settings in the Microsites YAML file.

    Microsite config image

    Current top-level keys used in the URL include tools, landing, and developer. If new top-level keys are required, clone this ticket.

  5. Test the microsite after it gets pushed.

    Any microsite edits are picked up once a day (midnight PT). Contact Bob if you want to push changes more quickly than that.

    Unfortunately, there is no distinction between stage and production microsites at this time. Microsites are rendered to production and stage simultaneously.

Add SEO metadata to your microsite content

If you want to add description or other metadata to your microsites, use a format similar to the following sample.

<!doctype html>
<html>
  <head>
    <title>Adobe Target Sample Size Calculator</title>
    <meta name="description" content="The Adobe Target Sample Size Calculator helps you determine the sample size needed for a successful A/B test.">

Note that metadata such as solution, role, level, and feature is not used in Experience League at this time.

Add Analytics tags to your microsite content

Not yet available. HTML is simple pass-through, with no out-of-the-box connection to EXL. Writers need to add their own analytics tagging.

If you want to create a site that uses the EXL header/footer, contact a member of the SSE team.

(Microsite developer) Work with microsites

  1. Create a JIRA ticket (project = UGP) assigned to Jacob Hammons. Explain the proposed purpose of your microsite.

    Once Jacob consults with stakeholders and approves the microsite, he will assign the JIRA ticket to a member of the engineering team.

  2. Contact Bob Bringhurst or Joseph Ross for setup details such as Git repo location and stage URL.

  3. Create a develop branch, and add your code.

  4. Test the code on stage (https://experienceleague.stage.adobe.com/<your_microsite_url>).

  5. When you’re ready to go live, create a PR and merge the develop branch into main.

(Admin config) Create microsites using the new Edge Platform method (alpha)

This is a one-time step required to configure a microsite.

Create the project in Adobe IO

  1. Sign in using your to developer.adobe.com Console. Select the Adobe Marketing Cloud project.

    https://developer.adobe.com/console/51837/projects

  2. On developer.adobe.com Console > Adobe Marketing Cloud, click Create new Project and select Project from template. Click the App Builder template.

    create new project image

  3. Click App Builder.

  4. Specify a Project name that starts with “Microsite”. Specify an App Name that starts with “Microsite” and doesn’t include spaces or special characters, such as MicrositeTargetCalc. It should only have a Production and Staging workspace.

  5. Click Save.

  6. Download the JSON files for both Production and Stage.

    After creation you’ll be taken to a page for the new project. Click into the Production environment. Click the Download all button. Repeat for Stage environment.

    These JSON files contain the values needed to populate the secrets in a microsite repo and to specify the app name when creating the microsites page in AEM.

Create the source microsite repo

  1. Create a new repo in AdobeEXLMicrosites.

  1. Copy files from the template microsite.

    Copy all files, including hidden files, EXCEPT for the .git folder. Don’t copy the .git folder, or you’ll override the git properties. TIP: Press Cmd+Shift+. to show/hide hidden files.

  2. If there’s existing code for the microsite, copy the files to the src folder.

  3. Go to Settings > Environments, and add the secrets from the JSON files you downloaded: two for prod, and two for stage.

    • AIO_RUNTIME_AUTH will be the long string after auth: (don’t include quotes)
    • AIO_RUNTIME_NAMESPACE will be be the string after name: (don’t include quotes)
    note tip
    TIP
    Opening the JSON files in Firefox makes it easier to read. Otherwise, in VSC or Text Edit, you need to search or scroll in a single line.

    You’ll also need the app_url: value for the next procedure.

Create the microsite pages in AEM

  1. In Chrome, create the microsite page in AEM for all three environments. (Safari didn’t work for me.)

    Dev:
    https://author-p122525-e1200861.adobeaemcloud.com/ui#/aem/sites.html/content/exlm/global/en/tools

    Stage:
    https://author-p122525-e1219192.adobeaemcloud.com/ui#/aem/sites.html/content/exlm/global/en/tools

    Prod:
    https://author-p122525-e1219150.adobeaemcloud.com/ui#/aem/sites.html/content/exlm/global/en/tools

  2. Click Create > Page and specify the title (omit “Microsite” from the title).

    The title (title ID) will determine the microsite URL (https://experienceleague.adobe.com/en/tools/title-id).

  3. Edit the page to add an iframe App block to the page with the URL from the JSON file you downloaded.

  4. Configure it to point to the file associated with the developer.adobe.com project.

    Use the app_url: value.

    Dev and stage will have the same app_url value. Production will have a different app_url value.

    The url will look something like: https://51837-micrositedynmeddemo-stage.adobeio-static.net/index.html. Until the initial version of the microsite is done, it won’t show anything. AEM dev and stage should use the developer.adobe.com stage urls and prod should use prod.

  5. Add relevant parties as non-Admins to the AdobeEXLMicrosites org so they can add their code and do their thing. Give them Write access to the repo in Settings > Collaborators and Teams.

Editing the microsite code

When the repo is fully configured, contributors should create a branch called develop and/or stage to view test content. When they’re ready to go live, create a PR and merge to main.

Contributors will get e-mail notifications about any PRs they merge up and will be able to check the status of the deploy actions to know if their PRs were deployed or if there was an issue. If a deploy fails I believe the author gets an e-mail notification. Changes should appear on the deployed env nearly immediately. Deploys normally only take a few seconds.

recommendation-more-help
92f1a422-8a81-400b-85d3-388f0c36dfda