The dotCMS Markdown Viewtool uses Github-flavored Markdown syntax. This document describes the most commonly used markdown features using this syntax.

Markdown Basics

Markdown allows you to write using an easy-to-read, easy-to-write plain text format, which then converts to valid HTML for viewing on dotCMS. This list of examples was taken from github.com, which has popularized markdown to the point that it has become a defacto web standard.

Markdown tags use simple characters and text conventions to allow the most common types of HTML formatting, without using HTML tags. Note that most markdown formatting does not require a closing tag or character.

Styling

When you use Markdown in dotCMS, dotCMS automatically applies standard styling to your Markdown-formatted text based on a pre-defined style sheet that ships with dotCMS.

Other than the formatting characters supplied by Markdown, can't apply specific styles to individual text elements within a markdown-formatted block of text.

However you can still use HTML formatting with specific styling within a Markdown document. Please see Mixing Markdown with HTML, below.

Mixing Markdown with HTML

When you create a document in dotCMS that uses Markdown, the document will also recognize all HTML tags. This allows you to use Markdown for the majority of your formatting, but also use HTML tags for more advanced formatting which

Markdown and Velocity

Important: You can not use Velocity code anywhere within your Markdown-formatted document. If you wish to use Velocity code within your document, you can not specify your document format as Markdown.

Common Formats

The following are some of the most common types of formatting used in HTML documents. Each includes a description, the equivalent HTML tags, and an example which displays both the Markdown formatted text and how the text will be displayed.

Paragraphs

To create paragraphs in Markdown, use one or more lines of consecutive text followed by one or more blank lines.

Note: If you don't leave a blank line between blocks of text, they will be collapsed into a single paragraph.

HTML Tags: <p></p>

Markdown:

On July 2, an alien mothership entered Earth's orbit and deployed several dozen saucer-shaped "destroyer" spacecraft, each 15 miles (24 km) wide.

On July 3, the Black Knights, a squadron of Marine Corps F/A-18 Hornets, participated in an assault on a destroyer near the city of Los Angeles.

On July 4, the aliens struck back.
On July 5, Los Angeles was evacuated.

Displayed:

On July 2, an alien mothership entered Earth's orbit and deployed several dozen saucer-shaped “destroyer” spacecraft, each 15 miles (24 km) wide.

On July 3, the Black Knights, a squadron of Marine Corps F/A-18 Hornets, participated in an assault on a destroyer near the city of Los Angeles.

On July 4, the aliens struck back. On July 5, Los Angeles was evacuated.

Headings

HTML Tags: <h1></h1>, <h2></h2>, etc.

To create a heading, add one or more has marks (#) at the beginning of a line, before your heading text. The number of hash marks you use will determine the size of the heading.

Markdown:

# The largest heading (an <h1> tag)
## The second largest heading (an <h2> tag)
...
###### The 6th largest heading (an <h6> tag)

Displays:

The largest heading (an <h1> tag)

The second largest heading (an <h2> tag)

…

The 6th largest heading (an <h6> tag)

Blockquotes

To create a blockquote, place a greater than symbol (>) at the beginning of a line.

HTML Tags: <blockquote></blockquote>

Markdown:

In the words of Abraham Lincoln:

> Pardon my french

Displayed:

In the words of Abraham Lincoln:

Pardon my french

---

Bold, Italic and Strikethrough

• To create bold text, surround the text with double asterisks (**).
• To create italic text, surround the text with single asterisks (*) or single underscores (_).
• To create strikethrough text, surround the text with double tildes (~~).
• To create text which is both bold and italic, surround the text with triple asterisks (***).
  • You may also use text formatting characters within text which is being formatted in another way (such as creating italic text within a block of bold text), by simply using the appropriate formatting characters on a portion of the enclosed text.

HTML Tags: (<b></b>|<strong></strong>), (<i></i>|<em></em>), <del></del>

Markdown:

*This text will be italic*

_This text will be italic_

**This text will be bold**

~~This text will be Strikethrough~~

***This text will be bold and italic***

**Everyone _must_ attend the meeting at ~~5 o'clock~~ 6 o'clock today.**

Displayed:

This text will be italic

This text will be italic

This text will be bold

This text will be Strikethrough

This text will be bold and italic

Everyone must attend the meeting at 5 o'clock 6 o'clock today.

Blank Lines

Markdown automatically joins elements such as text, list items, and code blocks, if there are no different types of elements between them. For example, if you create two lists (using the Markdown asterisk notation) with a blank line between them, the Markdown parser will automatically join them into a single list. You can use the following methods to add blank lines in your Markdown code:

• To add a single extra line after a paragraph, add two extra spaces (  ) at the end of the text.
• To add an extra line of space between paragraphs, add the HTML non-breaking space ( ) code, followed by two extra spaces (e.g.    ).
• To add an extra line in between elements which automatically join together (such as lists, you must use the following HTML notation:

  <p>&nbsp;</p>
  

For an example, please see the Unordered Lists example, below.

Lists

Unordered Lists

To create an unordered list, put each list item on a separate line, and precede each list item with either an asterisk (*) or a dash (-).

Notes:

• You do not need any header before the beginning of the list items.
• You do not need a blank line before the first list item (though it may help readability).

HTML Tags: <ul>, <li></li>, </ul>

Markdown:

* Item 1
* Item 2
* Item 3
<p>&nbsp;</p>
- Item 4
- Item 5
- Item 6

Displayed:

• Item 1
• Item 2
• Item 3

   

• Item 4
• Item 5
• Item 6

  ---

Ordered Lists

To create an ordered list, put each list item on a separate line, and precede each list item with a number.

Notes:

• You do not need any header before the beginning of the list items.
• You do not need a blank line before the first list item (though it may help readability).
• The numbers you place at the beginning of each list item do not matter; the list will automatically be re-numbered starting with the first list item.

HTML Tags: <ol>, <li></li>, </ol>

1. Item 1
2. Item 2
5. Item 5

Displayed:

1. Item 1
2. Item 2
3. Item 5

   ---

Nested Lists

To create a nested list, indent the list items by four spaces.

Markdown:

1. Item 1
    1. A corollary to the above item.
    2. Yet another point to consider.
2. Item 2
    * A corollary that does not need to be ordered.
        * This is indented eight spaces, because it's four spaces further than the item above.
        * You might want to consider making a new list.
3. Item 3

Displayed:

1. Item 1
   1. A corollary to the above item.
   2. Yet another point to consider.
2. Item 2
   • A corollary that does not need to be ordered.
     • This is indented eight spaces, because it's four spaces further than the item above.
     • You might want to consider making a new list.
3. Item 3

   ---

Code Formatting

Inline Format

Use single backticks (`) to format text in a special monospace format. Everything within the backticks appear as-is, colored red, with no other special formatting.

HTML Tags: <code></code>

Markdown:

Here's an idea: why don't we take `SuperiorProject` and turn it into `**Reasonable**Project`.

Displayed:

Here's an idea: why don't we take SuperiorProject and turn it into **Reasonable**Project.

Multiple Lines

To create a distinct block of text without formatting any of the text within the block, place triple backticks (```) on the lines before and after the block of text to be separated.

Notes:

• Unlike the HTML <pre> tag, HTML tags or Markdown tags within the text formatted in this way will not be interpreted.

HTML Tags: <pre></pre>

Markdown:

Check out this program I wrote:

```text
#comment
x = 0
x = 2 + 2
what is x
```

Displayed:

Check out this program I wrote:

#comment
x = 0
x = 2 + 2
what is x

Code Highlighting

In dotCMS, any text included within the triple backticks will automatically have code highlighting applied using the highlight.js library.

• Code highlighting includes both coloring and text formatting (such as bold) to certain keywords and characters as appropriate to the programming language specified.
• The default code highlighting applied is for the Java language.
• You may change the language used for code highlighting by adding the name of the language after the triple backticks.
  • For a list of languages supported and the aliases to use, please see the highlight.js documentation on readthedocs.io.
  • For example, to perform code highlighting for the Javascript language, begin the block with the following:
    

    ```javascript

• If you wish to display the text with no code highlighting, specify the language as text:
  

  ```text

Markdown:

Check out this program I wrote:

```c
#comment
x = 0
x = 2 + 2
what is x
```

```text
#comment
x = 0
x = 2 + 2
what is x
```

Displayed:

Check out this program I wrote:

#comment
x = 0
x = 2 + 2
what is x

#comment
x = 0
x = 2 + 2
what is x

Multiple Lines within a List

To create a multiple line code block within a list (indented appropriately for the level of the list item it applies to):

• Add a line of text following the list item it applies to.
• Do not add a list marker (e.g. no asterisk or number) to the line.
• Indent it 8 spaces from the list item it applies to
  • For example, if the list item is part of a nested list and indented 4 spaces, each line in the multi-line code block must be indented 12 spaces (4 for the nesting, plus 8 spaces).

Markdown:

* Item 1A
        Indented block that applies to Item 1A
    * Item 2A
    * Item 2B
            Indented code block
            that applies to Item 2B
    * Item 2C
* Item 1B

Displayed:

• Item 1A

  Indented block that applies to Item 1A
  

  • Item 2A
  • Item 2B

    Indented code block
    that applies to Item 2B
    

  • Item 2C
• Item 1B

  ---

Links

Inline Links

To create an inline link, wrap the link text in brackets ([ ]), followed immediately by the link (href) in parentheses (( )).

HTML Tags: <a href="..."></a>

Markdown:

The following hyperlink to www.github.com has link text that says "Visit GitHub!": [Visit GitHub!](https://www.github.com).

Displayed:

The following hyperlink to www.github.com has link text that says “Visit GitHub!“: Visit GitHub!.

Auto Linking

Any valid URL found within the text will automatically be converted to a clickable link.

HTML Tags: <a href=""></a>

Markdown:

Please go to http://demo.dotcms.com to try out dotCMS for yourself.

Displayed:

Please go to http://demo.dotcms.com to try out dotCMS for yourself.

Anchor Links

You can create an anchor link for a header or list item by ending the link with curly braces ({}) enclosing a hash mark (#) followed by the link id.

HTML Tags: <a id="..."></a>

Markdown:

##Header with ID {#headid}

* List item 1 with ID {#listid1}
* List item 2 with ID {#listid2}

Create a link to : [Headline with ID](#headid)

Displayed:

Header with ID

• List item 1 with ID
• List item 2 with ID

Create a link to : Headline with ID

Tables

To create a table:

• Begin each row of the table with a pipe (|).
• Divide the text for each additional column with a pipe.
• End each row with a pipe.
• Divide the header row from the body rows by creating a row where each column is filled with dashes (-).

Note: Although you may wish to line up the pipes between each column for ease of reading, it isn't required (see the second example below).

HTML Tags: <table></table>, <th></th>, <tr></tr>, <td></td>

Markdown:

| First Header  | Second Header |
| ------------- | ------------- |
| Content Cell  | Content Cell  |
| Content Cell  | Content Cell  |

You can include other inline Markdown within each table cell (such as links, bold, italics, or strikethrough:

| Name | Description          |
| ------------- | ----------- |
| Help          | ~~Display the~~ help window.|
| Close         | _Closes_ a window     |

By default, columns are left aligned. You can specify the alignment of any column by adding colons into each column of the header row separator, on the left (for left alignment), right (for right alignment), or both sides (for center alignmnent).

| Left-Aligned  | Center Aligned  | Right Aligned |
| :------------ |:---------------:| -----:|
| col 3 is      | some wordy text | $1600 |
| col 2 is      | centered        | $12 |
| zebra stripes | are neat        | $1 |

Displayed:

Images

Images are embedded similar to links, but preceded by an exclamation point (!).

HTML Tags: <img src="link" alt="description">

Markdown:

The following markdown:

![dotCMS logo](//dotcms.com/img/logo.png)

is equivalent to the HTML tag:

<img src="//dotcms.com/img/logo.png" alt="dotCMS logo">

Displayed:

Miscellaneous {#Miscellaneous)

HTML Codes: ©, ®, ™, –, —, …, «, », “, ”

Markdown:

* (C) becomes ©
* (R) becomes ®
* (TM) becomes ™
* -- becomes –
* --- becomes —
* ... becomes …
* << becomes &laquo;
* When *not* placed at the beginning of the line, >> becomes &raquo;
* "Text" becomes &ldquo;Text&rdquo;

Displayed:

• © becomes ©
• ® becomes ®
• ™ becomes ™
• – becomes –
• — becomes —
• … becomes …
• « becomes «
• When not placed at the beginning of the line, » becomes »
• “Text” becomes “Text”

  ---