Markdown Editor Syntax Rules and Specifications

• 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

* * *

*****

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

_ _ _ _

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.

• 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++

• Inline Links

  To create an inline link, use a set of regular parentheses immediately after the closing square bracket for the link text. Inside the parentheses, put the URL where you want the link to point, and optionally a title surrounded in quotes. Also, if you reference a local resource on the same server, you can use relative paths.

  Examples: Inline Link

  With a title:

  Text with [example link text](http://www.example.com/path "Title") inline link and title.

  Without a title:

  Text with [example link text](http://www.example.com/path) inline link without a title.

  Relative path:

  Text with [example link text](/relative_path/) inline link with relative path.

• Reference Links

  Reference-type links use a second set of square brackets that include a label (link identifier) to reference the target for the link (link identifier 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 (link identifiers) are only used for creating the links and do not appear in the output.

  Text with [link text1][id 1] a reference-type link and [link text2][id_2] another one.

  Then, somewhere in the document, you need to define your link label on a line by itself. The link identifier must be within square brackets followed by a colon, then after one or more spaces the URL for the link. Optionally this can be followed by a title enclosed in single quotes, double quotes, or parentheses. Also, the link may optionally be enclosed in angle brackets (< >).

  [id 1]: http://example1.com/ "Optional Title"
  [id_2]: <http://example2.com/> "Optional Title2"

  Other notes about Reference Links:

  • You can put the title on a second line and use extra spaces or tabs for padding. This is useful for aesthetics when the URL is long.

    [id]: http://example.com/long/path/to/resource/here
        "Optional Title Here"

  • The label (link identifier) can be missing, in which case the link text (in square brackets) is used as the name.

    [My Link][]

    and then defined as:

    [My Link]: http://example.com/

• URLs

  By surrounding a URL with angle brackets, you can show the actual text of the URL while also making it clickable in the output.

  <http://example.com/>

  For example, in HTML it is converted to:

  <a href="http://example.com/">http://example.com/</a>

• Email Addresses

  Automatic links for email addresses work similarly, except that Markdown will also perform a bit of randomized decimal and hex entity-encoding to help obscure your address from address-harvesting spambots.

  <address@example.com>

  In HTML, it is converted to something like:

  <a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
  &#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
  &#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
  &#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>

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

• 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")

• 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 Author 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;
  ```

This is a regular paragraph.

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

This is another regular paragraph.

• 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
      ```

- [ ] Unfinished task 1
- [x] Finished task 2

Term 1
: Definition A
: Definition B

• 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* |||

:smile:
:laughing:

\*literal asterisks\*

\   backslash
`   backtick
*   asterisk
_   underscore
{}  curly braces
[]  square brackets
()  parentheses
#   hash mark
+   plus sign
-   minus sign (hyphen)
.   dot
!   exclamation mark

• 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.]