Markdown Syntax Style Guide

This page illustrates the markdown componentry for Digital Experience Technical Documentation Authoring using the markdown (.md) format. This page includes details for Adobe employees.

• You can view the quick cheat sheet
• You can view a basic sample file or view a sample file with advanced syntax examples

Instructions

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.

Common Markdown Examples

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.

Blockquotes

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.

Characters to “escape”

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.

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 " > ".

Code Block (in line)

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.

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.

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.

Definition Lists

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.

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](/docs/authoring-guide-exl/assets/download-test.zip?lang=en)

Rendered:

Download download-test.zip

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}.
• We recommend only 3 heading levels. Levels 4 and beyond are not rendering properly at this time.

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.

HTML syntax

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.

Images

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.

![alt text](/docs/authoring-guide-exl/assets/logo.png?lang=en)

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.

• 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 1500 pixels. There is no need to create images larger than 2500 pixels or 500 kilobytes.
• For small images, create images using the desired width in pixels. Preview the content on the page to make sure you get the right results. If necessary, use image-editing software to change the image size.
• 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 editing down the wider images to improve consistency.

Links and Cross-References

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)

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.

Image Links

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

Syntax

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

Example

Click this image to go to the Adobe website.

Numbered Lists and Bullet 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 yet another step, the third.

Example

1. This is step 1.
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](/docs/authoring-guide-exl/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.

   

3. Make sure that your table looks like this:

   Hello	World
   How	are you?

4. This is the fourth step.

   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.

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.

Tables

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.

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.).

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 item 1 item 2 item 3	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.

Blank lines

You can add some breathing room to your walls of text with blank lines. Use <br>&nbsp; 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.

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, described next.

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.

Supported extensions

• Note (including Important, Tip, Caution, and Warning)
• Embedded video
• More Like This
• Various UI tags for localization
• Component properties (formatted in trailing braces {# } 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.

Note

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

Syntax

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

Example

Syntax

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

Example

Syntax

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

Example

Syntax

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

Example

Syntax

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

Example

New note types to be supported:

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/29770/?quality=12)

Example

More Like This

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

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.