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
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:
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
, andtooltip
parameters are optional. Thetype
parameter determines the color. Theurl
parameter lets users click the badge to open an article or page. Thetooltip
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
andtooltip
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:
orbadgeWeb
. -
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
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.
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
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.
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
:::

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

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

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
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.
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.
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:
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
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.
CONTEXTUALHELP
Authors can work with product teams to add help popovers in the Experience Cloud or Experience Platform product UI.
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
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 asmini-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.
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.

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)
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.
{width="300" align="center"}
Rendered:
- 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"}
. Thevalign
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.)
Image Links
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.
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
Syntax
{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, useclass="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 ®
) is preferred over other formats such as HTML code (such as ®
).
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.
Links and Cross-References 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:
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)
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:
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
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
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 supported note types:
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
-
This is step 1.
- Sub-step
- Sub-step
-
This is the next step.
-
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.

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:
table 0-row-2 1-row-2 Hello World How are you? -
This is the fourth step.
note note NOTE This is note text. -
Do another step.
This is an indented line.
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:
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;">
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
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.
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.
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:
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.
- Locate the text file of your video in the sources directory of the VideoTranscripts.en repo repo.
- Copy the text file of your video from the
sources
to theoverrides
directory. - Edit and save the override file.
- 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>
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>
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:
<
(<)>
(>)&
(&)^
(^)—
(—)–
(–)
A full list of HTML entities is available on the Freeformatter website. This will allow you to look up all special characters.
>
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 " > ".
To escape back ticks ( ` ), use `
or insert the back tick within triple back ticks that wrap an inline code block.
[
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.