Show Menu
TOPICS×

How to use Markdown for writing technical documentation

Adobe technical documentation articles are written in a lightweight markup language called Markdown , which is both easy to read and easy to learn.
As we are storing Adobe Docs content in GitHub, it can use a version of Markdown called GitHub Flavored Markdown (GFM) , which provides additional functionality for common formatting needs. Additionally, Adobe extended Markdown in a few ways to support certain help-related features such as notes, tips, and embedded videos.

Markdown basics

Headings

To create a heading, use a hash mark (#) at the beginning of a line:
   # This is level 1 (article title)
   ## This is level 2
   ### This is level 3
   #### This is level 4
   ##### This is level 5

Basic text

A paragraph requires no special syntax in Markdown.
To format text as bold , you enclose it in two asterisks. To format text as italic , you enclose it in a single asterisk:
    This text is **bold**.
    This text is *italic*.
    This text is both ***bold and italic***.

To ignore Markdown formatting characters, use \ before the character:
This is not \*italicized\* type.

Numbered lists and bullet lists

To create numbered lists, begin a line with 1. or 1), but don't use both formats within the same list, or you'll start a new list. You don't need to specify the numbers. GitHub does that for you.
1. This is step 1.
1. This is the next step.
1. This is yet another step, the third.

Displayed:
  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 don't mix the formats within the same list. (If you mix the formats, such as * and \+, you essentially start a new list.)
- First item in an unordered list.
- Another item.
- Here we go again.

Displayed:
  • 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.
1. Set up your table and code blocks.
1. Perform this step.

   ![screen](assets/no-localize/adobe_standard_logo.png)
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.

Displayed:
  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.
    This is note text.
  5. Do another step.

Tables

Tables are not part of the core Markdown specification, but Adobe supports them to an extent. Markdown doesn't support multiple lines lists in cells. Best practice is to avoid using multiple lines in tables. You can create tables by using the pipe (|) character to delineate columns and rows. Hyphens create each column's header, while pipes separate each column. Include a blank line before your table so it's rendered correctly.
| Header | Another header | Yet another header |
|------------|:---------------:|-----------------------:|
| row 1 | centered column 2 | right-aligned column 3 |
| row 2 | row 2 column 2 | row 2 column 3 |

Displayed:
Header
Another header
Yet another header
row 1
centered column 2
right-aligned 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.
For more information on creating tables, see:

Images

![Adobe Logo](assets/no-localize/adobe_standard_logo.png "Hover text")

Displayed:

Hover text

Code blocks

Markdown supports the placement of code blocks both inline in a sentence and as a separate "fenced" block between sentences. For details, see Markdown's native support for code blocks
Use back ticks ( \` ) to create inline code styles within a paragraph. To create a specific multi-line code block, add three back ticks (\`\`\`) before and after the code block (called a "fenced code block" in Markdown and just a "code block" component in AEM). For fenced code blocks, add the code language after the first set of back ticks so that Markdown correctly highlights code syntax. Example: \`\`\`javascript
Examples:
This is `inline code` within a paragraph of text.

Displayed:
This is inline code within a paragraph of text.
This is a fenced code block:
\```javascript
function test() {
 console.log("notice the blank line before this function?");
\```

Displayed:
function test() {
 console.log("notice the blank line before this function?");

You can specify properties for code blocks to turn off line numbers (on by default) or add a line wrap (off by default). Use and . These properties are custom Markdown extensions.
\`\`\`javascript function test() { console.log("notice the blank line before this function?"); \`\`\`

Definition Lists

A definition list is a Markdown extension that supports the Definition List component in AEM. A definition list consists of a term and its definition.

Remarks and comments

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.

Custom Markdown extensions

Adobe articles use standard Markdown for most article formatting, such as paragraphs, links, lists, and headings. For richer formatting, articles can use extended Markdown features such as:
  • Note blocks
  • Embedded videos
  • Do not localize
  • Component properties, such as assigning a different heading ID to a heading
Use the Markdown block quote ( > ) at the beginning of every line to tie together an extended component, such as a note. 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 > >.
Some common Markdown elements such as headings and code blocks include extended properties. If you need to change default properties, add the parameters in french braces /{ /} after the component. Extended properties are described in context.

Note blocks

You can choose from four types of note blocks to draw attention to specific content:
  • [!NOTE]
  • [!CAUTION]
  • [!TIP]
  • [!IMPORTANT]
In general, note blocks should be used sparingly because they can be disruptive. Although they also support code blocks, images, lists, and links, try to keep your note blocks simple and straightforward.
>[!NOTE]
>This is a standard NOTE block.

Displayed:
This is a standard NOTE block.
>[!TIP]
>This is a standard tip.

Displayed:
This is a standard tip.

Videos

Embedded videos won't natively render in Markdown, but you can use this Markdown extension.
>[!VIDEO](https://www.youtube.com/watch?v=A0EcD2AxvJE)

Displayed:

More Like This

The "More Like This" component in AEM appears at the end of an article. It displays related links. When the article is rendered, it can be formatted the same as level-2 headings (##) without being added to the mini-TOC.

DNL - Do Not Localize - and UICONTROL

In some cases, we need to flag certain sections of content within an article to be English only. Words, phrases and other elements need to be declared to our translation systems, and creates the ability to manage a controlled lexicon.
For words or phrases that should not be localized, use the [!DNL] extension to wrap the word or section.
For elements in the user interface and menus of a solution, we use the [!UICONTROL] extension.
Example:
In Adobe Target you can create your tests directly on a Target-enabled page.
Source:
In [!DNL Adobe Target] you can create your tests directly on a [!DNL Target]-enabled page.

Example
Use the Visual Experience Composer in Target to create your test directly on a page.
Source:
Use the [!UICONTROL Visual Experience Composer] in [!DNL Target] to create your test directly on a page.

Gotchas and troubleshooting

Alt text

Alt text that contains underscores won't be rendered properly. For example, instead of using this:
![Settings_Step_2] (/assets/settings_step_2.png)

OUr best practice is to use hyphens (-) instead of underscores (_) in filenames.
![Settings-Step-2] (/assets/settings-step-2.png)

Apostrophes and quotation marks

If you copy text into a Markdown editor, the text might contain "smart" (curly) apostrophes or quotation marks. These need to be encoded or changed to basic apostrophes or quotation marks. Otherwise, you end up with odd characters like this when the file is published: It’s
Here are the encodings for the "smart" versions of these punctuation marks:
  • Left (opening) quotation mark: “
  • Right (closing) quotation mark: ”
  • Right (closing) single quotation mark or apostrophe: ’
  • Left (opening) single quotation mark (rarely used): ‘

Angle brackets

If you use angle brackets in text (not code) in your file--for example, to denote a placeholder--you need to manually encode the angle brackets. Otherwise, Markdown thinks that they're intended to be an HTML tag.
For example, encode <script name> as &lt;script name&gt;

Ampersands in titles

Ampersands (&) aren't allowed in titles. Use "and" instead, or use the &amp; encoding.