Experience League tasks

Quick summary of your tasks for migration to ExL

  • Make sure your content is rendering properly. If you see a problem that you can’t fix, log a UGP JIRA issue.
  • Edit docs.adobe.com links to point to experienceleague.adobe.com.
  • Edit the solution and type metadata values as appropriate to improve search filter experience.
  • Learn how to activate content. You can either use the activate-exl Jenkins job or you can configure your repo to auto-activate.

See Cutover tasks below.

Address UI differences

The Experience League UX team makes changes that we need to account for. For example, the UX team has a new landing page design, breadcrumbs, and a different search experience with filters.

  • We edit the landing page content in the landing-pages.en repo. Feel free to edit and submit a PR. The Readme file in that repo explains landing page syntax, which is slightly different from the Markdown syntax we use in articles.
  • We’ve already populated repos with new metadata such as solution, type, and user-guide-description, which are used in landing pages and search filters. We’ll continue to add more metadata. You should review this solution and type metadata in your repo to improve the search experience. See Metadata.

Make syntax changes

The Experience League team uses a different rendering tool to output Markdown as HTML. For certain elements such as code blocks and native Markdown tables, the output should improve significantly. However, we might need to do some syntax cleanup work to improve output quality. Here are examples.

Balanced HTML tables

For example, in our AEM system, HTML tables display with equal column widths regardless of the amount of content in each cell. In the new EXL system, column width is determined by the amount of content. If you used HTML tables specifically to create balanced columns, you might need to change your approach.

Look through pages in staged Experience League content to make sure everything is OK.

Code blocks

Code blocks are rendered with syntax highlighting in Experience League. Add a language to code blocks to take advantage of this feature.

See the githubusercontent file for a list of valid languages.

In addition, code block syntax needs to be a little cleaner for EXL validation:

  • Code blocks must have start and end backticks.
  • Code blocks can only have 3 backticks, not 4 or more.
  • The start and end back ticks for a code block must be indented with the same number of spaces.
  • The code should even with or indented to the right of the backticks.

Note components

Experience League requires stricter syntax for note, important, tip, and other “adornment” components than docs.adobe.com. Specifically, you’re no longer allowed to add a space between > and [!NOTE], and >[!NOTE] should on its own line. The > characters should have the same indent level. Use the format:

>This is a note.


Use <!-- to start a comment and --> to end a comment.

Do not use <!--> to start or end a comment, or validation will fail.

Loc tags in links

For [!DNL] and [!UICONTROL] tags used in hyperlink text, use the following format:

[[!DNL Amazon Redshift]](connectors/databases/redshift.md)

We updated all instances of the previous format that used only one set of brackets.

Summary of validation differences

Jenkins EXL

  • Four code block backticks not allowed in EXL (only three)
  • Code block backticks must have the same indentation in EXL
  • Orphans (files that are linked to but not in the TOC) are flagged as errors in EXL
  • If an image link is indented too far, it’s flagged as an error
  • NOTE/TIP/IMPORTANT syntax with a space between > and [. Example: > [!TIP]
  • NOTE/TIP/IMPORTANT syntax in which the text starts on the same line as the adornment. Example: >[!NOTE] This is a note.
  • NOTE/TIP/IMPORTANT syntax must be well-formed. Example: >[!Note], >[TIP], and >[!FAQ] are flagged as errors.
  • NOTE/TIP/IMPORTANT > characters must have the same indentation.
  • Comments that begin or end with <!-->
  • Mismatched { } or [ ] (not checked in code blocks)

If you find more examples, please add them.

Understand the new workflow

The old system converts Markdown to DITA so that it can be uploaded to AEM. We then activate the content in AEM when we’re ready.

In the new system, we’ll create a package of the repo and upload it for preview. See Publish.

Tasks for post-cutover (#cutover-tasks)

Check content rendering

If you see a problem that you can’t fix, log a UGP JIRA issue.

Update links from docs.adobe.com to experienceleague.adobe.com

Links to docs.adobe.com will be redirected to EXL, but it’s a good idea edit your links to point directly to the appropriate EXL link.

For standard links:

  • search for (click Use Regular Expressions icon):


  • replace with:


For HTML links:

  • search for (click Use Regular Expressions icon):


  • replace with:


Check your results individually before you accept changes.

Edit solution and type metadata values

Users can filter content by content type and solution (products). In this example, a search for ‘integration’ shows content for all solutions. However, users can click a product to limit the search.

search filter

In this example, you might want to edit the article about integrating Campaign with Analytics so that the solution metadata includes both Campaign and Analytics:

solution: Campaign, Analytics

Learn how to activate content

You can use the activate-exl Jenkins job to activate content. You can also configure your repo to auto-activate.

See Publish.

On this page