Edit online

Markdown Editor Syntax Rules and Specifications

The Markdown editor in Oxygen XML Editor uses rules that were integrated from the most common set of default Markdown syntax rules along with many of the GitHub Flavored Markdown rules.

This topic lists the Oxygen XML Editor implementation of the most commonly used syntax rules.

Headers

The Markdown editor supports two styles of headers, Setext and Atx.

  • Setext Style

    Setext-style headers are underlined using equal signs (for first-level headers) and dashes (for second-level headers). Any number of equal signs or dashes will result in the same output.

    Example: Setext Style Headers
    First-Level Header (H1)
    ========
    
    Second-Level Header (H2)
    ------------
  • Atx Style

    Atx-style headers use 1-6 hash characters at the start of the line, corresponding to header levels 1-6. Optionally, you may close atx-style headers. This is purely cosmetic and the closing hashes do not need to match the number of hashes used to open the header. It is the number of opening hashes that determines the header level.

    Example: Atx Style Headers
    # H1 text #
    ## H2 text 
    ### H3 text ###### 
    #### H4 text
    ##### H5 text ###
    ###### H6 text

Horizontal Rules (for HTML output only)

You can produce a horizontal rule tag (<hr>) by placing three or more hyphens, asterisks, or underscores on a line by themselves (they also need to be preceded and followed by a blank line). Optionally, they can be separated by spaces.

Example: Horizontal Rules

* * *

*****

---------------------------------------

_ _ _ _

Paragraphs and Line Breaks

A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. The text at the beginning of a paragraph should not be indented with spaces or tabs. To create a new paragraph, simply insert a blank line in between them.
Important: When converting to HTML, if you break a paragraph on multiple lines (without a blank line in between them), it will create a break tag (<br>. When converting to DITA, the text is kept in a single paragraph in this case and a blank line is required to break a paragraph. This behavior differs slightly from the default Markdown rules.
Example: Paragraphs
This is a paragraph that contains
two lines of text. (In HTML, a break tag is created in between the two lines)

This is a new paragraph.

Styling Text

The Markdown editor supports some syntax rules for styling text (such as bold, italic, or strikethrough).
  • Italic (Emphasis)

    Text wrapped with one asterisk or underscore produces an italic (emphasis) tag.
    *italic*
    _italic_
  • Bold (Strong)

    Text wrapped with two asterisks or underscores produces a bold (strong) tag.
    **bold**
    __bold__
  • Strikethrough

    In HTML only, text wrapped with two tildes (~~) produces a strikethrough tag.
    ~~strikethrough~~
  • Underline

    Text wrapped with two plus signs (++) produces an underline tag.
    ++underline++
Tip: You can also combine these styling rules. For example, **BoldText _ItalicText_ BoldText** would produce italicized text within bold text. Also, if you surround an asterisk or underscore with spaces, it will be treated as a literal asterisk or underscore. To produce a literal asterisk or underscore at a position where it would otherwise be used as a styling delimiter, you can escape it with a backslash (for example, \*literal asterisks\*.

Images

The Markdown editor uses an image syntax that is intended to resemble the syntax for two types of links (inline and reference). In both cases, the syntax for images begins with an exclamation mark, followed by Alt attribute text surrounded by square brackets, and then followed by a set of parentheses that contain the URL or path to the image.

  • Inline Images

    For inline images, use a set of regular parentheses immediately after the closing square bracket for the Alt attribute text. Inside the parentheses, put the URL or path of the image, and optionally a title surrounded in quotes.

    Examples: Inline Images

    With a title:
    Text with ![Alt text](/path/to/img.jpg "Optional title") inline image and a title.
    Without a title:
    Text with ![Alt text](/path/to/img.jpg) inline link without a title.
  • Reference Images

    For reference-type images, use a second set of square brackets that include a label (image identifier) to identify the image (it may consist of letters, numbers, spaces, and punctuation and it is not case-sensitive). You can optionally use a space to separate the sets of brackets. The labels (image identifiers) do not appear in the output.
    Text with ![Alt text1][id] a reference-type image.
    Then, somewhere in the document, you need to define your image label on a line by itself. The image identifier must be within square brackets followed by a colon, then after one or more spaces the URL or path of the image. Optionally this can be followed by a title enclosed in single quotes, double quotes, or parentheses.
    [id]: url/to/image "Optional Title"

Blockquotes

The Markdown editor uses email-style greater than characters (>) for blockquotes. You only need to put the > before the first line of a hard-wrapped paragraph, but it looks better (and is clearer) if you put a > before every line.

  • Example: Blockquotes
    > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
    > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
    > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
    > 
    > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
    > id sem consectetuer libero luctus adipiscing.
  • Example: Nested Blockquotes

    Blockquotes can be nested by adding additional levels of > characters.
    > This is the first level of quoting.
    >
    > > This is nested blockquote.
    >
    > Back to the first level.
  • Example: Blockquotes with Other Markdown Elements

    Blockquotes can also contain other Markdown elements (such as headers, lists, and code blocks).
    > ## This is a header.
    > 
    > 1.   This is the first list item.
    > 2.   This is the second list item.
    > 
    > Here's some example code:
    > 
    >     return shell_exec("echo $input | $markdown_script")

Quoting Code (Inline and Code Blocks)

The Markdown editor supports quoting code or commands inline within a sentence or in distinct blocks.

  • Inline

    You can quote or emphasize code within a sentence (inline) with single backticks (`). The text within the backticks will not be formatted.

    Example: Inline Code Emphasis
    This is a normal sentence with a `code` in the middle. 
  • Code Blocks

    You can format code or text into its own distinct block by inserting a blank line before and after the content and using at least 4 spaces (or 1 tab), or by using opening and closing triple backticks (```) on separate lines.

    Example: Code Block
    This is a normal paragraph:
    
        This is a code block
    
    This is a normal paragraph:
    
    ```
    This is a code block
    ```

    One level of indentation is removed from each line of a codeblock and it continues until it reaches a line that is not indented (or until the closing backticks).

    Example: Code Block with Indentation
        tell application "something"
            beep
        end tell
    For example, in HTML the result would look like this:
    <pre><code>tell application "Foo"
        beep
    end tell
    </code></pre>

    You can also add an optional language identifier to enable syntax highlighting in your code blocks. The Oxygen XML Editor Markdown editor syntax highlight supports the following languages: Java, JavaScript, CSS, and Python. When publishing Markdown content as part of a DITA project, more language values are supported and produce syntax highlights in the published WebHelp or PDF outputs: How to Add Syntax Highlights for Codeblocks in the Output.

    Example: Syntax Highlighting in Code Block
    ```css
    input[type="submit"] {
        color: white;
        font-weight: bold;
    ```

Inline XHTML (for HTML output only)

The Markdown editor supports writing inline XHTML. Since Markdown is just a writing format, it requires a conversion for publishing purposes. If you are using the HTML conversion, for any markup that is not covered by Markdown syntax, you can simply use XHTML syntax.

Example: Inline XHTML
This is a regular paragraph.

<table>
    <tr>
        <td>Col 1</td>
        <td>Col 2</td>
    </tr>
</table>

This is another regular paragraph.

Lists

The Markdown editor supports ordered and unordered lists. You can also insert blockquotes and code blocks inside list items. List markers typically start at the left margin, but may be indented by up to three spaces.

  • Unordered Lists

    For unordered lists, you can use asterisks (*), plus signs (+), and hyphens (-) interchangeably.
    * List item 1
    + List item 2
    - List item 3
  • Ordered Lists

    For ordered lists, use numbers followed by periods. The actual numbers you use have no effect on the output. It simply converts them to list items within an ordered list and the actual number of list items will determine the numbers in the output.
    1. List item 1
    8. List item 2
    5. List item 3
  • Nested Lists

    You can create nested lists by indenting lines by three spaces.
    1. Ordered list item 1
       1. Nested ordered list item 1
       2. Nested ordered list item 2
          * 2nd level nested unordered list item 1
          * 2nd level nested unordered list item 2
             * 3rd level nested unordered list item 1
    2. Ordered list item 2  
  • Paragraphs Inside Lists

    If list items are separated by blank lines, Markdown will wrap the items in a paragraph in the output.
    * List item 1
    
    * List item 2
    For both DITA and HTML output, this would result in:
    <ul>
    <li><p>List item 1</p></li>
    <li><p>List item 2</p></li>
    </ul>
  • Multiple Paragraphs Inside Lists

    List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either 4 spaces or one tab. Optionally, you can also indent each line of a paragraph to make it look nicer.
    1.  This is a list item with two paragraphs. Lorem ipsum dolor
        sit amet, consectetuer adipiscing elit. Aliquam hendrerit
        mi posuere lectus.
    
        Vestibulum enim wisi, viverra nec, fringilla in, laoreet
        vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
        sit amet velit.
    
    2.  Suspendisse id sem consectetuer libero luctus adipiscing.
  • Blockquotes Inside Lists

    To put a blockquote within a list item, the blockquote delimiters (>) need to be indented so that they are under the first letter of the text after the list item marker.
    *   A list item with a blockquote:
        > This is a blockquote
        > inside a list item.
  • Code Blocks Inside Lists

    To put a code block within a list item, insert an empty line in between the list item and the code block, and the code block needs to be indented twice (with 8 spaces or 2 tabs), or if you are using the triple backticks method, the opening triple backtick needs to be indented with 4 spaces or 1 tab.
    *   A list item with a code block:
    
            This is a code block inside a list item
    
        ```
        This is a code block inside a list item using the backticks method
        ```

Task Lists

You can create task lists by prefacing list items with a hyphen followed by a space followed by square brackets (- [ ]). To mark a task as complete, use - [x].

Example: Task Lists
- [ ] Unfinished task 1
- [x] Finished task 2

Definition Lists

You can create definition lists by using a colon plus a space for each list item.

Example: Definition Lists
Term 1
: Definition A
: Definition B

Tables

You can create tables in the Markdown editor by using pipes (|) and hyphens (-).

  • Creating a Table

    Pipes are used to separate each column, while hyphens are used to create column headers. The pipes on either end of the table are optional. Cells can vary in width and do not need to be perfectly aligned within columns, but there must be at least three hyphens in each column of the header row.
    | First Header  | Second Header |
    | ------------- | ------------- |
    | Column 1 Row 1 Cell  | Column 2 Row 1 Cell  |
    | Column 1 Row 2 Cell  | Column 2 Row 2 Cell  |
  • Formatting Rules in Table Cells

    You can use formatting rules inside the cells of the table (such as links, inline code blocks, and text styling).
    | First Header  | Second Header |
    | --- | --- |
    | `inline code`  | Content with **bold text** inside cell  |
  • Aligning Text in Tables

    You can align text to the left, right, or center of a column by including colons (:) to the left, right, or on both sides of the hyphens within the header row.
    | Left-aligned | Center-aligned | Right-aligned |
    | :---         |     :---:      |          ---: |
    | Content Cell | Content Cell   | Content Cell  |
  • Joining Cells (Span a Cell Over Multiple Columns)

    You can join cells horizontally (span a cell over multiple columns) by using multiple consecutive pipe characters (|) to the right of the particular cell. The number of consecutive pipes indicate the number of columns the cell will span (|| for two, ||| for three, and so on).
    | First Header | Second Header | Third Header | Fourth Header |
    | ------------ | ------------- | ------------ | ------------- |
    | Content Cell | *Cell Span Over 3 Columns* |||

Emoji

You can add emoji in the Markdown editor by surrounding the EMOJICODE with colons (:EMOJICODE:).

Example: Emoji
:smile:
:laughing:

The resulting emoticons will appear in the output, but they are not displayed in the Preview pane.

For a full list of available emoji codes, see Emoji Cheat Sheet.

Backslash Escapes

You can ignore Markdown formatting by using backslash escapes (\) to generate literal characters that would otherwise have special meaning in the Markdown syntax. For example, if you want to surround a word with literal asterisks (instead of an italic or emphasis tag), you can use backslashes to escape the asterisks.
\*literal asterisks\*
The Markdown editor provides backslash escapes for the following characters:
\   backslash
`   backtick
*   asterisk
_   underscore
{}  curly braces
[]  square brackets
()  parentheses
#   hash mark
+   plus sign
-   minus sign (hyphen)
.   dot
!   exclamation mark

Automatic Escaping for Special Characters

The Markdown editor includes support for automatically escaping special characters such as angle brackets (< >) and ampersands (&). If you want to use them as literal characters, you must escape them as entities, as in the table below. The exception to this is in HTML output, if the special characters for a valid tag (for example, <b>), they are treated as literal characters and escaping is not necessary.

Literal Character Escaping Code
< &lt;
> &gt;
& &amp;

Footnotes

The Markdown editor in Oxygen XML Editor supports normal and inline footnotes. The following examples show the required syntax.

  • Example: Normal Footnote
    Here is a footnote reference,[^1]
    
    [^1]: Here is the footnote.
  • Example: Normal Footnote with Multiple Blocks
    Here is a footnote reference,[^longnote]
    
    [^longnote]: Here is the footnote with multiple blocks.
    
        Subsequent paragraphs are indented with 4 spaces or 1 tab to show that they
    belong to the previous footnote.
  • Example: Inline Footnote
    Here is an inline note.^[Inlines notes are easier to write, since
    you don't have to pick an identifier and move down to type the
    note.]

DITA-Related Markdown Syntax

For information about unique Markdown features for DITA projects, see Working with Markdown Documents in DITA. Also, for a list of Markdown rules and examples for DITA, see the Markdown DITA Syntax Reference.