This page illustrates the markdown componentry for Digital Experience Technical Documentation Authoring using the markdown (.md) format. This page includes details for Adobe employees.
Watch this AdobeDocs Markdown video.
If you are not using an editor that supports visual formatting, markdown might seem a little daunting, but in reality it has a simple syntax for formatting content.
The top of the document includes the required metadata for the article. It can also include optional metadata for items such as flagging an article for a private beta or turning off search index for legacy articles. For metadata syntax, see Metadata.
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.
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.
Our authoring system uses blockquotes syntax (>
at the beginning of lines) to identify custom markdown extensions for tips, notes, and videos. You can create actual blockquotes by adding a >
character in front of a paragraph.
This is a blockquote quotation.
>This is a blockquote quotation.
Several characters (# { } [ ] < > * + - . !
) have a special meaning in Markdown for creating headings, images, lists, and other components. 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
Use 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 code instead of the character. Examples of common HTML code:
<
(<)>
(>)&
(&)^
(^)—
(—)–
(–)A full list of HTML entities is available on the Freeformatter website. This will allow you to look up all special characters.
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 (<filename>
).
If you use HTML entities in code blocks, the entity text is not converted to the special character. For example, >
appears in a code block as " >
" instead of " > ".
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.
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.
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.
Syntax (roughly rendered)
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.
(Ignore the backslashes \ before the backticks in this example. We need those to show the example code.)
```javascript
generic code block here
```
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 and variable formatting
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 githubusercontent file
Variable syntax such as <i>italic</i>
is not supported in code blocks. To indicate variable text, one option is to use angle brackets < >
.
Line numbers, text wrap, and other extended properties for code blocks
We plan to add a few extended properties for code blocks:
{line-numbers="no"}
(turned on by default){line-wrap="yes"}
(turned off by default)These properties are not supported at this time.
For definition lists, we do not yet support standard Markdown syntax. Instead, use manual formatting such as this:
**Frog** - An amphibious green creature. Likes flies.
Rendered:
Frog - An amphibious green creature. Likes flies.
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](/docs/authoring-guide-exl/assets/download-test.zip?lang=en)
Rendered:
Download download-test.zip
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
#
) follows a blank line after the metadata in each article.##
) to level 4 (####
).## Release notes for 2016 {#release-notes-2016}
.Heading IDs
Heading IDs (also called anchor IDs) are required for deep linking to sections within articles. To specify a heading ID, use this format:
## Creating processing rules {#processing-rules}
Heading IDs should be lowercase and hyphenated.
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>
<ul> (unordered list / numbered list)
<ol> (ordered list / bullet 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> (ignore the space; I can't add a codeblock inside this codeblock)
If you want HTML syntax to be added to this list, please log a ticket or contact the SSE team.
Use the ![]()
syntax for images. The brackets [ ]
include alt text, and the parentheses ( )
include the image location. The exclamation mark distinguishes an image from a link. We don’t support hover text at this time.

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
Image size
At this time, there is no property for setting the image size in Markdown.
Watch this AdobeDocs Markdown video.
External links are straight-forward and can be rendered as a linked caption or a pure URL.
[Adobe](https://www.adobe.com)
Rendered:
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
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)
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.
If you want to allow users to click an image to jump to a different page, use this format.
Syntax
[](https://www.adobe.com)
Example
Click this image to go to the Adobe website.
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 yet another step, the third.
Example
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
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.

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
Set up your table and code blocks.
Perform this step.
Make sure that your table looks like this:
Hello | World |
---|---|
How | are you? |
This is the fourth step.
This is note text.
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.
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.
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.
Tables are problematic in Markdown. When tables are migrated from the previous authoring system, simple tables (one line per cell) are formatted as native Markdown tables (preferred). More advanced tables are formatted as HTML.
Watch the Markdown Tables video
Native tables frequently look better in Markdown. Columns are sized according to their content. HTML tables are rendered with equal-width columns.
By default, Markdown doesn’t support multiple lines or lists in cells. However, we have extended Markdown tables to allow multiple lines in cells (using <br>
) or basic lists (using <ul><li>
etc.).
Be careful when adding these HTML codes to Markdown tables. If your syntax is incorrect, you’ll get a confusing validation error that doesn’t accurately describe the problem. Check your HTML syntax to make sure that it’s well-formed.
Not allowed in any table: iframes, spans of cells, embedded tables.
Not allowed in native Markdown table: nested or complex lists.
See Tables
Syntax
| Header | Another header | Yet another header |
|--- |--- |--- |
| row 1 | row 1 column 2 | row 1 column 3 |
| row 2 | row 2 column 2 | row 2 column 3 |
Example
Header | Another header | Yet another header |
---|---|---|
row 1 | row 1 column 2 | row 1 column 3 |
row 2 | row 2 column 2 | row 2 column 3 |
Simple tables work adequately in Markdown. However, tables that include multiple paragraphs or lists within a cell are difficult to work with. For such content, we recommend using a different format, such as headings & text.
Markdown table with line breaks and lists
| Header | Another header | Yet another header |
|------------|----------|----------------|
| row 1 | first line in cell<br>second line in cell | row 1 column 3 |
| row 2 | bullet list<ul><li>item 1</li><li>item 2</li><li>item 3</li></ul> | row 2 column 3 |
Example
Header | Another header | Yet another header |
---|---|---|
row 1 | first line in cell second line in cell |
row 1 column 3 |
row 2 | bullet list
|
row 2 column 3 |
Markdown table with line breaks and fake list
Workaround with manual bullets.
| Color | Things to Do |
|--- |--- |
| Red | * Read <br> * Write <br> * Study |
| Blue | * Swim <br> * Run <br> * Lift <br> **Note**: Remember to train smart.|
Example
Color | Things to Do |
---|---|
Red | * Read * Write * Study |
Blue | * Swim * Run * Lift Note: Remember to train smart. |
You can add some breathing room to your walls of text with blank lines. Use <br>
as a workaround to add a blank line.
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.
This may not seem very impressive here, but try out blank lines when you feel like your pages are too crowded.
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, described next.
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.
{# }
such as for heading IDs)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.
We extended Markdown to format various types of notes: Note, Tip, Important, and Warning.
Syntax
>[!NOTE]
>
>This is a standard NOTE block.
Example
This is a standard NOTE block.
Syntax
>[!TIP]
>
>This is a standard tip.
Example
This is a standard tip.
Syntax
>[!WARNING]
>
>This is a standard warning block.
Example
This is a standard warning block.
Syntax
>[!IMPORTANT]
>
>This is a standard important block.
Example
This is a standard important block.
Syntax
>[!NOTE]
>
>This is a standard NOTE block.
>
>It includes multiple paragraphs.
Example
This is a standard NOTE block.
It includes multiple paragraphs.
New note types to be supported:
This is an admin note. EXL only.
This is an availability note. EXL only.
This is a Prerequisites note. EXL only.
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/29770/?quality=12)
Example
Use the “More Like This” component to display related links at the end of an article. When rendered, the Related Articles component is rendered as “Related Articles” (and localized in other languages).
Syntax
Example
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.