Markdown syntax guide

For the most part, we follow standard git-flavored markdown (GFM) syntax for formatting text. However, some syntax (such as horizontal lines) is not supported, and we’ve extended Markdown in a number of ways to suit our documentation needs.

Basic text formatting

A paragraph requires no special syntax in Markdown. Add a blank line between each paragraph.

To format text as bold, you enclose it in two asterisks:

This text is **bold**.

To format text as italic, you enclose it in a single asterisk:

This text is *italic*.

To format text as both bold and italic, you enclose it in three asterisks:

This is text is both ***bold and italic***.

To ignore Markdown formatting characters, use \ before the character:

This is not \*italicized\* type.

Rendered: This is not *italicized* type.

Badges

A badge is a colored label used as a content indicator. For example, you can add a badge to mark an article as Beta or a section as Premium. You can change the color of a badge and associate a URL and tooltip.

[Badge Example]{class="badge informative"}

There are two types of badges, each with differing syntax:

  • Metadata - Displays the badge near the top of a page
  • Inline - Displays the badge where the syntax is located

badge examples {width="200" modal="regular"}

Metadata badges

Adding badge syntax in metadata places a badge above the page title (H1) in the article.

You can name badges, for example, using badge1 or badge2. Or, you can be more creative (as long as the name begins with badge).

Metadata examples:

badgePremium: label="Premium" type="Positive" url="https://www.premium-product.com" tooltip="Download Premium"
badgeExam: label="Exam ADO-E903" type="neutral" before-title="false"
  • badgePremium: This example displays a Premium badge with a URL and tool tip.

  • badgeExam: This example displays a dark badge with an exam ID number.

Inline badges

Specify the badge information on its own line or in a heading, table, or other page element.

Here’s the syntax for an inline badge with a beta label, blue color, URL, and tooltip:

[!BADGE Beta]{type=Informative url="https://www.example.com" tooltip="Go to example.com"}

Available badge colors

Badges use colors defined in Adobe Spectrum:

Type
Badge
Informative (default)
[Beta]{class="badge informative"}
Positive
[Premium]{class="badge positive" title="Go to example.com"}
Negative
[Discontinued]{class="badge negative" title="This feature is now end of life"}
Neutral
[Maybe]{class="badge neutral" title="A rider fell off the horse..."}
Caution
[Attention]{class="badge yellow" title="Yellow status"}

Syntax examples

|Type|Badge|
|---|---|
|Informative (default)|[!BADGE Beta]{type=Informative url="https://www.example.com"}|
|Positive|[!BADGE Premium]{type=Positive url="https://www.example.com" tooltip="Go to example.com"}|
|Negative|[!BADGE Discontinued]{type=negative tooltip="This feature is now end of life"}|
|Neutral|[!BADGE Maybe]{type=Neutral tooltip="A rider fell off the horse..."}|
|Caution|[!BADGE Attention]{type=Caution tooltip="Yellow status"}|

Requirements for badges

  • Only two badges are allowed in metadata. This rule is configurable, so let us know if you need an exception.

  • Only the badge label is required. The type, url, and tooltip parameters are optional. The type parameter determines the color. The url parameter lets users click the badge to open an article or page. The tooltip parameter displays the tooltip text on mouseover.

  • Adding a badge to the TOC.md file displays the badge on every article in the guide. If you specify a URL for the badge to jump to an article, make sure that you use a root link (e.g., /help/guide/article.md) not a relative link (e.g., article.md) to account for articles in different folders.

  • Adding a badge to metadata.md displays the badge on every article in a repo.

  • If you have an important reason for a metadata badge to appear below the H1, add before-title="false"to the badge syntax (shown in the badgeExam example above).

  • For metadata badges, make sure that all values are wrapped in quotes. For inline badges, make sure that url and tooltip are wrapped in quotes.

  • Valid type values include Informative (default, blue), Positive (green), Negative (red), Neutral (dark gray), and Caution (yellow).

  • Badge labels are localized.

  • If multiple metadata badges are specified, badges are displayed in alphabetical order based on the badge name, such as badge1: or badgeWeb.

  • If you want the URL to open in a new tab, use this syntax:

    code language-none
    [!BADGE Open in new tab]{type=Negative url="https://www.adobe.com" newtab=true tooltip="Open adobe.com in new tab"}
    

    Rendered:

    [Open in new tab]{class="badge negative" title="Open adobe.com in new tab"}

Editorial guidance for badges editorial-badges

Use badges sparingly to clarify potentially confusing product information. Or, use badges frequently in a permanent location that you maintain regularly.

Before you add a badge, determine:

  • Placement - Top of page or inline. Place the badge where readers expect to see it and where it applies.
  • Localization - Badge names are translated, so be consistent and concise.
  • Color - Use colors are recommended below (they follow Spectrum design). Consider using blue as a default. If you need multiple colors, discuss this with your product management team and use them consistently.
  • Upkeep - Do not add a badge for information that easily becomes obsolete after time, such as New.

Here are examples of when to use a badge

Situation
Example
Reason
Colors
Product SKU
[Premium]{class="badge positive"} or [Standard]{class="badge informative"}
The customer might not know if they purchased the product you’re documenting.
Green is attractive for Premium. You can determine colors for other types, but be consistent.
Product version
[Campaign v8]{class="badge positive"} or [Campaign Classic]{class="badge informative"} or [2023.2.0]{class="badge positive"}

You need to call out a product version because it’s not otherwise clear.

For example, the ExL breadcrumb is insufficient to determined the product.

Or, you need to apply the label to information embedded in another product’s page.

Or, you consistently show a version number on a badge in the same location each release.

Go with blue, green, and black.
Product status
[Beta]{class="badge informative"} or [Deprecated]{class="badge neutral"}
Customer needs to know a release status.
Use blue for Beta and black for Deprecated and Discontinued.
A download link
[PDF]{class="badge informative"}, [PowerPoint]{class="badge informative"}
You have a link to download a hosted PDF, PowerPoint, or CSV file.
Go with blue for download links.
ID number
[Exam ID: ADO-E902]{class="badge neutral" title="Exam ID: ADO-E902"}
Customer needs to know certification information
Use black for ID information.
A stand-alone link to a different content type
[Tutorial video]{class="badge informative"} or [Documentation]{class="badge informative"}

Customer could benefit from a use-case tutorial for a feature, or the product documentation.

Do not use badges to replace headings like More information, Recommended topics, and Related information

Blue coordinates with the color of link text.
When not to use a badge
If metadata exists.

Do not use badges for situations where metadata exists that we can leverage programmatically in the future. Examples: role, feature, solution, type, and so on (the values in YAML files). (Create a ticket requesting a feature to expose metadata as a badge.)

However, if you have a rare need to call out a role like Administrator or Developer, use a badge.

Blue or green

Blockquotes

Our authoring system uses blockquotes syntax (> at the beginning of lines) to identify custom markdown extensions for tips, notes, and videos. We don’t support blockquote components.

For example, if you add this syntax at the beginning of a line:

>This is a blockquote quotation.

It will be rendered as this:

This is a blockquote quotation.

Cards (beta)

At this point, cards are a beta feature used only in the journey-optimizer.en repo as part of the RedPen work. Cards are not yet fully implemented. There are known display issues, and they do not work in preview or review environments.

Syntax

:::: landing-cards-container
:::
![icon](https://cdn.experienceleague.adobe.com/icons/list-check.svg)

What's New

Stay updated with the latest changes.

[View What's New](https://experienceleague.adobe.com/docs/authoring-guide/using/whats-new.html?lang=en)
:::

:::
![icon](https://cdn.experienceleague.adobe.com/icons/circle-play.svg)

Get Started

Learn the basics of Git setup.

[Get Started](https://experienceleague.adobe.com/docs/authoring-guide/using/setup/tools/git-setup.html?lang=en)
:::

:::
![icon](https://cdn.experienceleague.adobe.com/icons/code-branch.svg)

Cheat sheet

Condensed version of the markdown syntax guide

[Explore Journeys](https://experienceleague.adobe.com/docs/authoring-guide/using/markdown/cheatsheet.html?lang=en)
:::

::::

Rendered

icon

What’s New

Stay updated with the latest changes.

View What’s New

icon

Get Started

Learn the basics of Git setup.

Get Started

icon

Cheat sheet

Condensed version of the markdown syntax guide

Explore Journeys

Code Block (in line) code-block

When to use

Used to render a piece of code in-line in a sentence. Ideal to call out a cookie name, file name, value, or command that does not require a full-fenced code block.

Content within code blocks in rendered as is and not localized. (The one exception to this rule is !UICONTROL and !DNL syntax, which is stripped out during packaging for publication.)

Also use code blocks for sample URLs that should not be validated: https://www.example.com

Syntax

A code block uses single backticks to enclose the code element you would like to highlight.

This is `inline code` within a paragraph of text.

Example

This is inline code within a paragraph of text.

TIP
You can also wrap text in triple back ticks (```) to create an inline code block. This is especially useful when you need to reference a back tick character within an inline code block. Example:
```Use a back tick (`) for formatting```

Code Block (fenced)

When to use

Use a code block to display code syntax. A fenced code block uses triple backticks to enclose the code element you want to highlight. Add blank lines above and below the fenced code block.

Note that code blocks are not localized.

TIP
Specify a language when you create a fenced code block. Specifying a language allows syntax highlighting specific to that language and displays a Copy button for the users. You can also display line numbers if you specify a language.

Syntax

Use three back ticks ( ``` ) before and after the code lines. Make sure that the open and close back ticks are indented the same number of spaces. For optimal rendering, specify a code language.

```javascript

Example

var visitor = Visitor.getInstance("INSERT-MARKETING-CLOUD-ORGANIZATION ID-HERE", {
     trackingServer: "INSERT-TRACKING-SERVER-HERE", // same as s.trackingServer
     trackingServerSecure: "INSERT-SECURE-TRACKING-SERVER-HERE", // same as s.trackingServerSecure

     // To enable CNAME support, add the following configuration variables
     // If you are not using CNAME, DO NOT include these variables
     marketingCloudServer: "INSERT-TRACKING-SERVER-HERE",
     marketingCloudServerSecure: "INSERT-SECURE-TRACKING-SERVER-HERE" // same as s.trackingServerSecure
});

Syntax highlighting for code blocks

Experience League supports syntax highlighting for code blocks. Make sure that you specify a language such as java after the opening set of back ticks to make sure that the syntax is highlighted properly. For a list of valid languages, see https://prismjs.com. If any languages are missing, please log a jira ticket.

Line numbering in code blocks

Add {line-numbers="true"} after the language to enable line numbering.

Example with line numbers (````html {line-numbers=“true”}`):

<!DOCTYPE html>
<html>
<body>

<h1>My First Heading</h1>
<p>My first paragraph.</p>

</body>
</html>

Start numbering on line _

Add start-number="n" after line number syntax to start the numbering on a number other than 1.

Example with new start line (````html {line-numbers=“true” start-line=“7”}`):

<!DOCTYPE html>
<html>
<body>

<h1>My First Heading</h1>
<p>My first paragraph.</p>
<p>My second paragraph.</p>

</body>
</html>

Line highlighting in code blocks

Add highlight="n" after line number syntax to highlight rows within a code block. Specifying 11-13, 16 will highlight lines 11 through 13 and 16.

Example with line highlighting (````html {line-numbers=“true” start-line=“7” highlight=“11-13, 16”}`):

<!DOCTYPE html>
<html>
<body>

<h1>My First Heading</h1>
<p>My first paragraph.</p>
<p>My second paragraph.</p>

</body>
</html>

Adding backtick characters within code blocks

To include a literal backtick character within a code block, you can use multiple backticks as the opening and closing delimiters:

nested backtick

Variable formatting in code blocks

Variable syntax such as <i>italic</i> is not supported in code blocks. To indicate variable text, one option is to use angle brackets < >.

Collapsible sections

You can create a collapsible section (sometimes called an accordion) that is hidden by default. The user can click the title to expand or collapse the section.

Collapsible text can be used to simplify complex content, such as streamlining an FAQ page or de-cluttering a complex procedure with nested lists. For example, instead of displaying a set of sub-steps, you can collapse the sub-steps into a “View details” section.

Syntax

+++See details
This is text inside a collapsible section.

* Bullet one
* Bullet two
* Bullet three

+++

Example

See details

This is text inside a collapsible section.

  • Bullet one
  • Bullet two
  • Bullet three

Notes

  • Do not nest collapsible sections within collapsible sections. Nested collapsible sections do not render properly. However, they don’t cause validation to fail, so users will see the +++ syntax of the nested section.
  • Make sure that you add blank lines above and below items like bullet lists and code blocks inside the collapsible section, or you’ll get a validation error.
  • You can add headings inside collapsible sections, but it’s not recommended.
  • Accordions Are Not Always the Answer for Complex Content on Desktops
  • One historical drawback of collapsible sections is that Find in Page (Ctrl/Cmd+F) ignores collapsed text. While that’s still true in Safari, it’s no longer true in Chrome; Find in Page detects collapsed text in Chrome.
  • Collapsible test file
  • Example of a maintenance updates page using collapsible sections.

Comments and Remarks

Comments do not appear in the rendered help system. Use comments to leave notes for yourself or other writers. You can also use comments for draft sections of text.

For comments, keep in mind that while they are not rendered in the help system, they are visible to users who edit Markdown files on GitHub.com. Don’t include confidential information in comments.

<!-- standard comment code -->

DO NOT USE the following:
<!--> bad comment syntax <-->

You shouldn’t be able to see text below this (“You can’t see me”) unless you’re editing the document.

Reminder: Comments (remarks) do not appear in the public-facing help articles. However, comments do appear in the public-facing Markdown files that users can see and edit.

IMPORTANT
Avoid adding comments within block components such as bullet lists, especially nested bullet lists. The comment can change how the bullet list is rendered.
In the TOC.md file, do not comment out lines in the middle of the TOC list. This might break up the TOC list and cause validation errors. Instead, move comments in the TOC to the end of the file.

CONTEXTUALHELP

Authors can work with product teams to add help popovers in the Experience Cloud or Experience Platform product UI.

See Contextual Help Popovers.

Definition Lists

For definition lists, we do not support common Markdown syntax. Instead, use manual formatting such as this:

**Frog** - An amphibious green creature. Likes flies.

Rendered:

Frog - An amphibious green creature. Likes flies.

Download Files

Upload the .zip or other downloadable file to the assets directory, and then link to it. If it’s a .zip file, clicking the link will download the file. If it’s file type such as PDF or PNG that can be opened in a browser, clicking the link will open a new tab. For such files, consider zipping them or providing instructions to right-click the link and download.

Download [download-test.zip](https://experienceleague.adobe.com/docs/authoring-guide/assets/download-test.zip?lang=en)

Rendered:

Download download-test.zip

NOTE
The maximum file size for download files and images is 100 MB. That’s the github.com limit. The git.corp.adobe.com limit is higher (250 MB), but we need to be able to copy files to the github.com mirror.
If you need to use a file larger than 5 MB as an image or download file, please log a JIRA ticket, and we’ll host the file for you outside of Git.

Headings headings

In Markdown, you use pound signs (#) to identify heading levels. The first level (#) is the article title, which is also specified in the metadata header—keep these the same. The second level (##) represents the main headings on the page that will be included in the mini-TOC. If you’re accustomed to writing in AEM (chl-author), the level 2 headings (##) map to the “Heading 1” component in AEM.

Maximum character count for headings: 69 characters (English) / 120 characters (LOC).

# This is level 1 (article title)

## This is level 2

### This is level 3

Heading best practices

  • Make sure that a level 1 heading (#) follows a blank line after the metadata in each article.
  • Don’t skip levels, such as jumping from level 2 (##) to level 4 (####).
  • Include a blank line before and after each heading.
  • If a heading includes numerals, specify an explicit heading ID that does not begin with a number, such as ## Release notes for 2016 {#release-notes-2016}.
  • Headings are displayed in the right nav so that users can click to jump to a section. By default, two levels of headings appear in the right nav. If you want to change the number of levels, use mini-toc-levels metadata, such as mini-toc-levels: 3. See Using metadata.

Heading IDs

Heading IDs (also called anchor IDs) are used to create custom deep links to sections within articles. To specify a heading ID, use this format:

## Creating processing rules {#processing-rules}

Heading IDs should be lowercase and hyphenated.

If you don’t specify a heading ID for a heading, the default heading ID is the “slugified” (lowercase and hyphenated) heading. For example, the ## Creating widgets and Such heading will have a #creating-widgets-and-such anchor.

HTML syntax html

For various reasons, including security and accessibility, we limit the HTML syntax that can be used in markdown. The following list shows supported HTML syntax. Any HTML syntax not on this list will result in a validation error.

<table>
<tbody>
<td>
<tfoot>
<thead>
<th>
<tr>
<col>
<colgroup>
<p> (paragraph break)
<ul> (unordered list / bullet list)
<ol> (ordered list / numbered list)
<li> (list item)
<br> (line break)
<b>
<caption>
<i>
<strong> (bold)
<u> (underline)
<s> (strikethrough)
<span>
<sub> (subscript)
<sup> (superscript)
<a>
<img>
<div>
<em> (emphasis, italics)
<pre> (codeblock)
<code>
<​codeblock>

If you want HTML syntax to be added to this list, please log a ticket or contact the SSE team.

NOTE
Please use markdown syntax whenever possible. Ideally, HTML syntax should be used only for special tables, such as tables that do not have a header. Using HTML syntax outside of tables should be avoided, especially in cases where markdown syntax can be used.

Images images

Use the ![]() syntax for images. The brackets [ ] include alt text, and the parentheses ( ) include the image location and optional hover text (tooltip). The exclamation mark distinguishes an image from a link.

![alt text](/docs/authoring-guide/assets/logo.png "Hover text")

alt text

For shared images, you can place the images in a root assets folder and then use a root link that works from any file within a repo:

/help/assets/imagename.png

Resizing and aligning images

Image properties (with right-aligned image) alt text {align="right"}

Use syntax such as the following to change the default image width or center or right-align the image within the page view or table cell.

![Dive image alt text](/docs/authoring-guide/assets/maui-dive.jpg "Hover text - Maui dive width is 300 pixels and centered"){width="300" align="center"}

Rendered:

Dive image alt text {align="center" width="300"}

  • For large images, we recommend that you create images large enough to be scaled down to fit within the page width—at least 640 pixels wide. Recommended width is up to 2000 pixels. There is no need to create images larger than 2500 pixels or 500 kilobytes. The maximum file size for images is 100 MB.
  • For small images, create images using the desired width in pixels, or use the width parameter, such as {width="250"} (pixels) or {width="50%"} (percentage of view area, not original image size). Images are scaled proportionally. Note that images can be scaled up or down with this parameter, so be careful about pixelation.
  • In some cases, images from the same interface will look out of proportion on the page because wider images (such as a toolbar) are scaled down while narrow images (such as a panel) are not scaled down. In such cases, consider scaling down the wider images to improve visual consistency.
  • You can change the alignment of an image within the view area. Use either {align="center"} or {align="right"}. The valign parameter is not supported.

Editorial guidance for screenshots

See Screenshots to learn about screenshot guidelines (when and where to add them, how to shoot them, adding borders, callouts, and so on.)

If you want to allow users to click an image to jump to a different page, use this format.

Syntax

[![image](https://experienceleague.adobe.com/docs/authoring-guide/assets/core-services_96.png?lang=en)](https://www.adobe.com)

Example

Click this image to go to the Adobe website.

image

Click-to-zoom images

Use the zoomable parameter to allow users to click an image to view an enlarged version of the image. When the user mouses over a zoomable image, the pointer becomes a magnifying glass. When clicked, the image expands to the full width of the browser. It can be dismissed with a close button.

Example

Diving image {width="100" modal="regular"}

Syntax

![Diving image](/docs/authoring-guide/assets/maui-dive.jpg "Diving in Maui"){width="100" zoomable="yes"}

Click-to-zoom notes

  • Don’t use click-to-zoom on images that are also links. The hyperlink takes precedent over the zoom.
  • If you are using the HTML <img> tag to load the image, use class="modal-image" to make the image zoomable.
  • There is a known issue with transparent backgrounds. We’re adding a background color per UGP-8559.

Image size recommendations

Make image files large enough to fit within the page width, but keep image files smaller than 5 MB.

Using the default image size settings for screen capture programs is usually fine. However, overly large files can be a problem, so a validation warning appears if an image asset (or download file) is larger than 5 MB; a validation error appears if an image asset is larger than 20 MB. Assets larger than 100 MB should pose a serious problem if added to the repo. The github.com limit is 100 MB. Assets over 100 MB will cause the mirror sync to fail, and the fix is not as simple as removing the file.

If you need to use a file larger than 5 MB as an image or download file, please log a JIRA ticket, and we’ll host the file for you outside of Git.

Icons and inline images

Inline icons are aligned to the text baseline. If the icon’s screen shot includes extra bottom space, the image may appear to float above the text. For best results, edit the image to remove or reduce the extra space.

If possible, use HTML characters instead of images for items such as arrows and symbols. See the following resource:

HTML Currency Symbols, Currency Entities and ASCII Currency Character Code Reference

The HTML entity (such as &reg;) is preferred over other formats such as HTML code (such as &#174;).

HTML icons

Image limitations

Our authoring pipeline imposes image limitations that might not be flagged as validation errors:

  • Image size - Avoid adding images larger than 5 MB. This is a Git limition. Adding an image that is larger than 100 MG causes serious problems with Git history that are difficult to resolve.
  • Number of images in an article - Avoid adding more than 100 images to an article. This is an EDS limitation. If you add more than 100 images, the article will not render properly.

External links are straight-forward and can be rendered as a linked caption or a pure URL.

[Adobe](https://www.adobe.com)

Rendered:

Adobe

If you add a URL directly to text, it is not converted to a link automatically. If you want a URL to appear as a link, add < > syntax. Examples:

https://www.adobe.com

<https://www.adobe.com>

Rendered:

https://www.adobe.com

https://www.adobe.com

Links to articles (cross-references) can be a little more complex.

Option 1: Standard relative link

Here’s what a standard relative link looks like:

See [Overview example article](collaborative-doc-instructions/overview.md)

The pathname needs to account for both the location of the source file and the target file. You can use all relative link operands, such as ./ (current directory), ../ (back one directory), and ../../ (back two directories).

Option 2: Root relative link

The advantage to this type of link is that it needs to account for only the target file. It works from any source file within the repo regardless of source file location.

/help/using/docile-rules/introduction.md

To learn more about adding root links, see Linking tips.

Deep linking

To link to a heading within an article, the target heading must have an explicit heading ID (also called an “anchor ID”). Example:

## Creating audience segments {#creating-audience-segments}

To link to this heading within the same page, use the heading ID as the link:

See [Creating audience segments](#creating-audience-segments)

To link to this heading from a different article in the repo, add the heading ID suffix to the end of the link:

See [Audiences: Creating audience segments](audiences.md#creating-audience-segments)

Open in new tab

If you want a link to open a new tab, such as when you jump to a different guide, use the {target="_blank"} property in the link.

Example:

[See What's new](https://experienceleague.adobe.com/docs/authoring-guide/using/whats-new.html?lang=en){target="_blank"}

Rendered:

See What’s new

Metadata

Add metadata to the top of the markdown file. The next line after the metadata line (and blank line) MUST be the article title (# Title).

---
title: Title for search optimization
description: This is the article description used for search optimization. Use common search keywords and synonyms.
---

# Article title

For a list of required and optional metadata, see Metadata.

Localization tags: UICONTROL, DNL, and DONOTLOCALIZE

All of our Markdown help content is localized using machine translation initially. If the help has never been localized, then we keep the machine translation. However, if the help content has been localized in the past, then the machine translated content will act as a placeholder while the content is in the process of human translation.

See Localization best practices - UICONTROL and DNL for instructions on these tags.

More Like This

Use the MORELIKETHIS component to display related links at the end of an article. When rendered, the MORELIKETHIS component is rendered as “Related Articles” (and localized in other languages).

Syntax

More like this syntax

Example

Notes / admonitions

We extended Markdown to format various types of notes: Note, Tip, Important, and Warning.

Syntax

>[!NOTE]
>
>This is a standard NOTE block.

Example

NOTE
This is a standard  NOTE block.

Syntax

>[!TIP]
>
>This is a standard tip.

Example

TIP
This is a standard  tip.

Syntax

>[!WARNING]
>
>This is a standard warning block.

Example

WARNING
This is a standard warning  block.

Syntax

>[!IMPORTANT]
>
>This is a standard important block.

Example

IMPORTANT
This is a standard important  block.

Syntax

>[!NOTE]
>
>This is a standard NOTE block.
>
>It includes multiple paragraphs.

Example

NOTE
This is a standard NOTE  block.
It includes multiple paragraphs.

New supported note types:

ADMIN
This is an admin note. EXL only.
AVAILABILITY
This is an availability note. EXL only.
PREREQUISITES
This is a Prerequisites note. EXL only.
INFO
This is an Info note. EXL only.
ERROR
This is an Error note. EXL only.
SUCCESS
This is a Success note. EXL only.

Numbered Lists and Bullet Lists lists

For editorial guidance, see Steps and lists

To create numbered lists, begin a line with 1. or 1), but pick one method and use it consistently within the article. You don’t need to specify the numbers. GitHub does that for you.

Use the number 1 for every step in the numbered list.

Add blank lines before and after lists.

Syntax

1. This is step 1.
1. This is the next step.

   1. This is a sub-step
   1. This is a sub-step

1. This is yet another step, the third.

Example

  1. This is step 1.

    1. Sub-step
    2. Sub-step
  2. This is the next step.

  3. This is yet another step, the third.

To create bullet lists, begin a line with * or - or +, but pick one method and use it consistently within the article. (If you mix the formats, such as * and +, you’ll get a Markdown validation error when you check in the file.)

Best practice: Use * for bullets. Visual Studio Code applies the asterisk for bullets, so it’s easier to stay with asterisks to automate creating an unordered list. (You might have noticed that the TOC.md file uses plus signs + for lists. That’s a holdover from migration. Any valid bullet character would work as long as it’s consistent within the article.)

Syntax

* First item in an unordered list.
* Another item.
* Here we go again.

Example

  • First item in an unordered list.
  • Another item.
  • Here we go again.

You can also embed lists within lists and add content between list items. Indent content between list items to avoid starting a new list. Items between steps should be indented to the start of the text—3 spaces for numbered lists, 2 spaces for bullet lists.

1. Set up your table and code blocks.
1. Perform this step.

   ![screen](https://experienceleague.adobe.com/docs/authoring-guide/assets/core-services_96.png?lang=en)

1. Make sure that your table looks like this:

   | Hello | World |
   |---|---|
   | How | are you? |

1. This is the fourth step.

   >[!NOTE]
   >
   >This is note text.

1. Do another step.

   This is an indented line.

Example

  1. Set up your table and code blocks.

  2. Perform this step.

    screen

  3. Make sure that your table looks like this:

    table 0-row-2 1-row-2
    Hello World
    How are you?
  4. This is the fourth step.

    note note
    NOTE
    This is note  text.
  5. Do another step.

    This is an indented line.

NOTE
If you indent too far, such as 6 spaces instead of 3, the content in that line will be treated as a code block.

Shade Boxes

Shade boxes are useful for setting off a section of content from the rest of the page. For example, the Workfront team likes to add “Example” boxes that contains text, images, and code samples to achieve a specific purpose. A shade box might also be useful for “On Your Own” or “Use Case” sections, or for extended notes or tips.

To create a shade box, add >[!BEGINSHADEBOX] at the beginning of the section and >[!ENDSHADEBOX] at the end. All content between these begin and end tags will have a gray background. Adding a label to BEGINSHADEBOX (such as >[!BEGINSHADEBOX "Use Case"]) is an optional way to create a bolded shade box title. You can also just add bold text or a heading on the next line.

Example:

recommendation-more-help

Removing the border in an HTML table

In some cases, you use an HTML table to create a balanced design, but you don’t want the content to look like a table. To turn off a border for a one-row HTML table, use this syntax:

<table>
<tr style="border: 0;">
NOTE
Don’t overuse. For normal tables, we want to keep a consistent design across content.

table tip

In a three-column table, you can also add <td align="center"> and <td align="right"> to distribute the cell content evenly across the view area. If it were not so, I would have told you.

This is the last line of the shade box.

Snippets and includes

To share text among articles in a repo, you create a _includes folder in the help folder. This _includes folder can have .md files that can be referenced (included) from other files in the repo. In addition, a snippets.md file in this repo can include Head2 anchors that can be referenced from any file in the repo.

Reference to H2 in snippets.md file:

{{id-name}}

Reference to include file:

{{$include /help/_includes/filename.md}}

For details, see Includes and snippets.

Tables

Standard Markdown supports only basic tables. For AdobeDocs Markdown, you have the following options:

  • Basic Markdown tables
  • HTML tables
  • Markdown tables with limited HTML syntax for paragraph breaks (<p>), line breaks (<br>), and basic lists (<ul>, <ol>).

You can also change how tables are rendered (auto or fixed).

For more details about tables, see Tables.

Tabs

A tab is a clickable area at the top of a section that shows different content. When a tab is clicked, the tab’s contents are shown, and the contents of other tabs is hidden.

To create a tab set, add >[!BEGINTABS] at the beginning of the tab set and >[!ENDTABS] after the last tab. Add >[!TAB <tab title>] tags for each tab section, and add the contents of each tab below it.

Tab syntax

>[!BEGINTABS]

>[!TAB iOS]

This content appears in the iOS tab.

>[!TAB Android]

This content appears in the Android tab.

>[!TAB Windows]

This content appears in the Windows tab.

>[!TAB MacOS]

This content appears in the MacOS tab.

>[!TAB Linux]

This content appears in the Linux tab.

>[!ENDTABS]

Rendered

iOS
This content appears in the iOS tab.
Android
This content appears in the Android tab.
Windows
This content appears in the Windows tab.
MacOS
This content appears in the MacOS tab.
Linux
This content appears in the Linux tab.

Tab notes

  • Users cannot use in-page search (Ctrl+F/Cmd+F) to locate content within tabs that are not displayed.
  • If the tab titles extend beyond the page view width in the user’s browser, a horizontal scroll bar appears.
  • You cannot format the tab titles. Any syntax you add will be passed through as part of the title. For example, >[!TAB **iOS**] will be displayed as **iOS**.
  • You can create multiple tab sets on a page, but you cannot nest a tab set within another tab set.
  • You cannot nest tabs sets within lists.
  • A shaded background is applied to the tab set so that users can see distinguish the tab content from other content.

Text highlighting

The Workfront team asked to be able to use yellow highlighting to indicate the preview of upcoming features. Here’s how it works.

Example:

This entire paragraph should NOT be highlighted. <span class="preview"> This word is **bold** inside a highlighted sentence.</span> And this is just the last sentence.

Rendered:

This entire paragraph should NOT be highlighted. This word is bold inside a highlighted sentence. And this is just the last sentence.

As a general rule, use <span class="preview"> to highlight a paragraph or text within a paragraph, and use <div class="preview"> for multiple paragraphs and components.

Video

Videos won’t natively render in Markdown. To display a video inline, use the component indicator [!VIDEO] and then the url.

Use URLs for uploaded videos. We do not support direct links to video files. For details on uploading videos, see Uploading Videos to Adobe TV.

Syntax

>[!VIDEO](https://video.tv.adobe.com/v/27069/?quality=12&learn=on)

Example

For best playback results, add ?quality=12&learn=on at the end of the video URL.

To play a video automatically when the page loads, add the ?autoplay=true parameter.

Autoplay syntax example: <div class="extension video"><iframe allowfullscreen embedded-video src="https://video.tv.adobe.com/v/27069/?autoplay=true" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"><source src="https://video.tv.adobe.com/v/27069/?autoplay=true" type="" /><p>Your browser does not support the iframe element.</p></iframe></div>

Adding video transcripts

Video transcripts can be added for any video.

video transcript

For a transcript to appear, the video uploaded to AdobeTV/MPC must have a transcript (SRT) file and an associated text file. These files should be created automatically.

TIP
To see if a transcript is available for a video, use this URL, replacing 111111 with the video ID.
https://video.tv.adobe.com/vc/111111/eng.json

To enable video transcripts in your repo, you can do one of the following:

  • Add auto-video-transcripts: true in the TOC.md or metadata.md to enable transcripts in all videos in the guide or repo by default. You can still turn off transcripts for any individual video in the guide or repo.
  • Add {transcript=true} to a VIDEO component as shown below.

Syntax:

>[!VIDEO](https://video.tv.adobe.com/v/3422473/?quality=12&learn=on){transcript=true}

Example:

Transcript
Hi, I’m Jamie Lynn Barna, and I’m a Senior Manager of Customer Success for Customer Journey Management at Adobe. I’m a Marketo Certified Expert and a Marketo Certified Solution Architect. I’ve been using Marketo Engage and working with our marketing automation customers for eight years. Inheriting a Marketo Engage instance can be a stressful time. Whether you’re an experienced admin or whether you are a newer admin, it can be difficult to know where to start. In this video, I will be talking about post-implementation Marketo Engage, which can be filled with best practice design, architecture, and use case development. It can run like a well-oiled machine, providing meaningful analytics geared towards recognizing ROI. It can also be riddled with mixed best practices, personal preference for build and setup, and misaligned architecture to current use cases. The longer the instance is running in live, the more complex understanding of the setup and architecture can be. Together, we will look at the most important sections in Marketo Engage to help you get started with auditing an inherited instance, and I will be sharing my tips and tricks along the way. To know how to approach owning an inherited instance of Marketo Engage, you will need to understand what is in the instance today. From there, you can create a plan of action to make any necessary adjustments to your configuration and setup. As marketers, much of what we can report on, build, and execute in Marketo Engage starts at the foundational setup within our Admin Panel. This will help add context for future discoveries around any limitations, data challenges, or reporting misalignments. Let’s start with a review of your Users and User Roles to determine an answer for your business. How many users are there? What permissions or access does each role have? Should any be adjusted? How often are your users logging in? Quick tip! While in the section for Users and Roles, visit your audit trail to understand what actions the users are taking. Next, consider reviewing your email defaults and email setup for branding, your SPF and DKIM, your tracking links, and landing pages. Is the appropriate branding in place? To protect the branding you have in place, we will start with your Smart Campaign settings. Do you have a restriction on Smart Campaign size? If not, consider adding one. A quick tip is to set your Smart Campaign limits to be no less than 25% of your total database. By setting a limit for your Smart Campaign processing, you will help mitigate manual error of processing the entire database in Smart Campaigns, which can lead to a backlog of activity or accidental email distribution. Once you look at your Smart Campaign settings, review your communication limits. Does your instance have appropriate communication limits? Adobe recommends one per day and three per week with non-operational emails blocked if over the limit. These limits prevent overcommunication to your database while protecting your brand. Finally, look to ensure your Campaign Inspector is turned on in the treasure chest setup. This is a quick tip that will help you when you look to audit the activity of your instance in marketing activities. Navigate to the Marketo database and look at your system smart lists. Adobe recommends a marketable database of at least 85% or more. If yours falls under this threshold, look at the other system lists with greater scrutiny. Block list, marketing suspended, duplicates, and unsubscribe. Consider the rules in which your record would qualify for an unmarketable status. Does this align to your business use case? Do you need to consider a strategy to clean up your database? Quick tip, when auditing your database, also consider taking a look at your field management. What fields are available? How consistent or normalized is the data? Is the proper formatting in place to keep your database accurate and usable? After reviewing your database setup and marketability, look at your program structure in marketing activities. Your program structure can deeply impact your efficiency and ability to report on the marketing impact to ROI. Do you have a consistent and easily navigable folder structure? Is there a center of excellence with program templates or program shells, which are cloneable program setups for consistency in building? If so, do those program templates make sense for your current business use cases? Are similar program types consistently structured? Adobe recommends utilizing program templates for consistent and scalable program creation. Remember when we reviewed in the Admin panel setup and enabled within the treasure chest the campaign inspector? Here in Marketing Activities is where you can benefit from that setup. Navigating in Marketing Activities, you can see the campaign inspector, which helps you view or search all of your smart campaigns in one place. Look to understand which campaigns are active, scheduled to run, or invalid. Do the active workflows meet your business requirements? Do you have a campaign processing backlog in the campaign queue? In the final part of our high-level audit, we will review the Design Studio. In reviewing your creative assets, consider how easily it is to navigate your folder structure and types of assets. Look to the number of assets per template. Adobe recommends global assets for consistency in updating and branding. A quick tip is to look for higher ratio in use by references per template versus single use templates. This can indicate a global asset structure. As you navigate through your audit, you will want to ensure you document the setup clearly. This could be documentation like a data dictionary, an implementation workbook, or a user enroll log and more. This will not only help serve as a starting point for creating an action plan for the changes you will need to make, but will also allow you to track changes ongoing and document the process or requirements for the setup decisions you make. I recommend ensuring that this is stored on your company’s cloud drive to help with easy collaboration and keeping that documentation up to date. A quick tip for further auditing and troubleshooting is to subscribe to Marketo notifications. Notifications keep you up to date on system events happening in your Marketo subscription. For example, campaign failure notifications inform you about errors in your smart campaigns. And CRM sync notifications alert you to critical issues found with the CRM sync, such as incorrect permissions or the sync being down. By navigating to the notifications, you can choose to subscribe to a subset or all the available notifications and receive an email when an event occurs. Now you are ready to review your legacy instance of Marketo Engage and put into practice what you learned from this tutorial. Remember to start within your admin panel. Take time to focus on each key area of Marketo Engage to evaluate if the current setup aligns to your current business needs and document your findings so you can get familiar with the legacy instance and improve instance efficiency for your internal users. Well that’s a wrap for this instructional video. I hope you find it helpful for evaluating the configuration and setup of your inherited instance. Don’t forget to check out the additional resources to apply the tips to your instance audit work and check out our tutorials on managing your instance effectively. Thanks so much for tuning in!

Previewing and editing video transcript files

When videos are uploaded to AdobeTV/MPC, an SRT transcript file is created for most videos. Once a day, ExL harvests the SRT files if available and creates a text file in the sources folder of the VideoTranscripts.en repo.

The README file in the VideoTranscripts.en repo lists all the available text files as well as the links to videos that do not have associated SRT files.

Obtaining missing transcript/SRT files

Transcript files should be added for videos in MPC, but some videos are missing transcript files. If a transcript file is missing in AdobeTV/MPC, contact Sean Schnoor to resolve the issue.

Obtaining missing video text files

If a video text file is missing (a new video, or a video that was recently added to our documentation), the text file can be generated using this Jenkins job. Fill in a list of MPC urls (one per line).

Editing a text file

In some cases, you might want to do minor cleanup such as fixing line breaks or fixing spelling or capitalization errors.

  1. Locate the text file of your video in the sources directory of the VideoTranscripts.en repo repo.
  2. Copy the text file of your video from the sources to the overrides directory.
  3. Edit and save the override file.
  4. If you want to see the results immediately, run the MPC Video Transcript Harvester, and then edit an article in your repo so that the transcript can be fetched.

Additional markdown syntax information

Extended Markdown Components

We need to extend Markdown to support items that aren’t included in common Markdown.

Special components are declared in a containing block quote using square brackets and an exclamation mark plus the reference for the type of block it is. For example, here’s how to declare a note:

>[!NOTE]
>
>This is a note.
  • Notes (admonitions), including Note, Important, Tip, Caution, and Warning
  • Embedded video
  • More Like This (Related articles)
  • Various UI tags for localization
  • Component properties for headings, images, and code blocks
  • Collapsible sections
  • Text highlighting
  • Page tabs

Use the Markdown block quote ( > ) at the beginning of every line to tie together a paragraph-based component, such as a note. To improve preview, add a line immediately after the start of the section that has only a block quote symbol (>). To end the section, add a blank line.

If you need to use subcomponents within components, add an extra level of block quotes (> >) for that subcomponent section. For example, a NOTE within a DONOTLOCALIZE section should begin with > >.

In some cases, we need to support specific settings for Markdown elements such as headings. If you need to change default settings, add the parameters in french braces {# } after the component.

Blank lines

If you add multiple hard returns in a markdown file, the extra hard returns are ignored. Use <br>&nbsp; as a workaround to add a blank line. This can be useful for adding some breathing room to sections of text you want to emphasize.

Example: This is a first sentence of what could be a really long text. Let me insert a blank line between this paragraph and the next.

The above line includes <br>&nbsp; on its own line.

Characters to “escape” characters-to-escape

Several characters (# { } [ ] < > * + - . !) have a special meaning in Markdown or HTML for creating headings, images, lists, and other components. When you use these characters, the rendering engine thinks you’re adding code. However, in some cases, you want to display these characters in your text. To do that, you need to “escape” the characters. The easiest escape method is to precede the character with a backslash (\). For example, if you want to start a line with a # character so that it’s not interpreted as a heading, you would type \#:

\# This is not a heading

Rendered:

# This is not a heading

The backslash works only with these characters: # { } [ ] * + - . !. If you need to escape characters such as angle brackets (such as <yourname>), you can either enclose the text in back ticks to apply an inline code block, or use the HTML entity code instead of the character. Examples of common HTML codes:

  • &lt; (<)
  • &gt; (>)
  • &amp; (&)
  • &Hat; (^)
  • &mdash; (—)
  • &ndash; (–)

A full list of HTML entities is available on the Freeformatter website. This will allow you to look up all special characters.

NOTE
For chain steps such as “Choose File > Save As,” you don’t need to escape the > character because it’s not next to other characters. For variables such as <filename> you’ll want to escape the angle brackets using either code block backticks or character codes (&lt;filename&gt;).

If you use HTML entities in code blocks, the entity text is not converted to the special character. For example, &gt; appears in a code block as " &gt; " instead of " > ".

To escape back ticks ( ` ), use &grave; or insert the back tick within triple back ticks that wrap an inline code block.

NOTE
Escaping characters in the metadata section requires a different approach than escaping markdown syntax. The metadata section at the top of the document uses YAML format, which has different rules.
As a rule of thumb, if you add special characters such as a colon or a [ at the start of the value, add parentheses around the metadata value like this:
---
title: "Processing rules: A new beginning"
---

Unsupported items

There are a few Git-flavored Markdown items that we don’t plan to support. The preview tool you use might enable some of these features, but don’t rely on that.

Task List

Not supported

* [x] Set up Jersey Shore recording
* [x] Buy donuts with sprinkles
* [x] Take nap
* [ ] Wash ferret

Emoji

Not supported

:bowtie:

Horizontal rule

Not supported

***

Block quotes

We use block quotes (> at the beginning of a line) to indicated extended Markdown syntax such as notes and videos, described next. But you can also use > syntax to create a block quote section.

Sample block quote that starts with > This is...:

This is a sample block quote. It looks like a code block.

NOTE
If you indent too far, such as six spaces instead of three, the content is rendered as a block quote. Use the proper amount of indenting to avoid having the content rendered mistakely as a block quote.
92f1a422-8a81-400b-85d3-388f0c36dfda