Markdown Help

The Red Hat Knowledgebase uses Markdown, not HTML, to format text.

About Markdown

Markdown can render most common formatting and styles. The philosophy behind Markdown emphasises readability and ease of use. While certain in-line HTML code is currently accepted, its use is not encouraged.

NOTE: To escape a character and render it literally, use a backslash (\) before the character.

Markdown in Red Hat Knowledgebase Comments

When using markdown in comments on the Red Hat Knowledgebase, only markdown for code blocks and links will be rendered.

All other markdown will render as plain text.

Table of Contents

• Blockquotes
• Code Blocks
• Inline Code Blocks
• Emphasis
• Footnotes
• Headers
• Horizontal Rules
• Line Breaks
• Links
  • External Links
  • Reference Links
  • Internal (Anchored) Links
• Lists
  • Ordered Lists
  • Unordered Lists
• Tables
• Adding Images
• More Information

Blockquotes

Separate blockquotes from surrounding text with blank lines and begin lines with ">". For example,

> this is a blockquote

shows the following:

this is a blockquote

Code Blocks

The best (possibly Drupal-specific) option is to separate code blocks from surrounding text with blank lines and then begin and end the block with 3 tildes.

~~~
this is a
code block
~~~

Another method is to separate code blocks from surrounding text with blank lines and indent each line of the block by 4 spaces. Tab does not consistently work, so if you are encountering issues, try manually entering spaces.

    this is a 
    code block

NOTE: If your code block follows a bullet or a numbered item, you must indent each line of the block by 8 spaces (it means 4 spaces * each indented level + 4 spaces). For instance, when you write the following:

- list item A 

        this is a code block under list item A.
        Note: you must indent 8 spaces for this code block.

    1. indented list item 1

            this is a code block under indented list item 1.
            Note: you must indent 12 spaces for this code block.

        and also you would like to put another code block under same level (Note: you must start this line with indent 8 spaces): 

            this is another code block under indented list item 1.
            Note: you must indent 12 spaces for this code block.

    2. indented list item 2

            this is a code block under indented list item 2.
            Note: you must also indent 12 spaces for this code block.

then the above shows the following:

• list item A

  this is a code block under list item A.
  Note: you must indent 8 spaces for this code block.
  

  1. indented list item 1

     this is a code block under indented list item 1.
     Note: you must indent 12 spaces for this code block.
     

     and also you would like to put another code block under same level (Note: you must start this line with indent 8 spaces):

     this is another code block under indented list item 1.
     Note: you must indent 12 spaces for this code block.
     

  2. indented list item 2

     this is a code block under indented list item 2.
     Note: you must also indent 12 spaces for this code block.
     

Inline Code Blocks

For inline code blocks, surround word(s) with `backquote`.

Emphasis

For italics, surround word(s) with *single asterisks*.
For bold, surround word(s) with **double asterisks**.
For bold italics, surround word(s) with ***triple asterisks***.
For bold italics then dropping to just italics, start with ***triple, end with** to get into italics, then end that*

Footnotes

Footnotes can be created using "^" plus a number in square brackets. Footnotes must each have a unique number, and you cannot create two links to the same footnote. For example:

Here is an example of text that requires a footnote.[^1]

[^1]: Here is the actual footnote. **Please note** that the colon is **required** for the footnote syntax to work properly.

shows the following:

Here is an example of text that requires a footnote.¹

Headers

Start lines with "#"s to mark headers. NOTE: a space must be used after the series of # and header title: # My Header, not #My Header.
# H1 (almost always reserved for title only)
## H2
### H3
#### H4
##### H5
###### H6

Alternatively underline the header for first two levels (line has to be at least as long as the title):

Header 1
=========

Header 2
---------

Horizontal Rules

For a horizontal rule, use 3 hyphens (---) or underscores (___) on a line.

Line Breaks

To insert a line break, end the line with two spaces.

NOTE: This is inaccurate as of 2016-01-06:

1. all linebreaks in the input are preserved
2. linebreaks are sometimes inserted in very long lines

Both of these can cause problems when using HTML formatting instead of pure markdown. Be extra careful when using indented HTML/XML/SVGs with empty lines. For example the following will cause the rest of the page not rendered as the closing style is translated into <code><pre> &lt;/style&gt;</pre></code>:

<svg>
    <defs>
        <style>
            .selector {}

        </style>
    </defs>
</svg>

Links

Markdown can be used to create external and internal (anchored) links.

External Links

To create a link, put the name of the link in square brackets, followed by its URL in parentheses. The link title is optional and should be in double-quotes within the parentheses. For example:

This is [a markdown example](http://example.com/ "Title") inline link.

shows the following:

This is a markdown example inline link.

Reference Links

Reference links provide a convenient way of maintaining all your links in one place and simply referencing them by name when you want to use them in your text.

To define the link, put the name of the link in brackets on its own line at the end of your text body followed by a colon and a space and the URL. For example:

[My Cool Link]: http://example.com "Hover title..."

The link title is optional and must be enclosed in quotes ("<title>").

To use the link reference, you would then put the name of the link in brackets followed by an empty set of brackets. For example:

Here we will use the [My Cool Link][] link reference.

You can use a different label for the link as well by placing the label in the first set of brackets and moving the link name to the second set of brackets. For example:

Here we will use the [example link reference][My Cool Link].

Putting it altogether:

Here we will use the [My Cool Link][] link reference.
Here we will use the [example link reference][My Cool Link 2].

Other text that has nothing to do with our links.

We define our link references anywhere within the body. As long as they are in the correct format and on their own line, they will not be displayed.

[My Cool Link]: http://example.com "What ever you would describe My Cool Link as"
[My Cool Link 2]: http://example.com/other-place "Hover title for My Cool Link 2 - Other place"

Shows the following:

Here we will use the My Cool Link link reference.
Here we will use the example link reference.

Other text that has nothing to do with our links.

We define our link references anywhere within the body. As long as they are in the correct format and on their own line, they will not be displayed.

Internal (Anchored) Links

To link to items within the same document, such as to create a table of contents, put a "#" followed by the anchor name inside curly brackets after the header at the end of the line. For example:

## H2 ## {#header}

NOTE: In order to use internal links with headers, you must use "#" both before and after the header name, as shown in the previous example.

NOTE 2: The above note is inaccurate as of 2016-01-06. One can use ## H2 {#header} or underlined headers:

Header2 {#header}
==================

You can then link to the anchor just like you would link to an external document. For example:

This is [a markdown example](#header) internal link.

shows the following:

This is a markdown example internal link.

Lists

Separate lists from surrounding text with blank lines.

Ordered Lists

Ordered Lists require an empty line before and after.

Begin lines with a number and period.

1. ordered list item 1
2. ordered list item 2

NOTE: If you have multiple paragraphs of text between items in an ordered list, you must indent each paragraph by 4 spaces * each indented level. If you do not do this, Markdown might restart numbering. Or another solution is begin lines with number and parenthesis, such as "1)". Markdown will not register a number followed by a parenthesis as part of a numbered list, so check to make sure you have numbered the items correctly.

Unordered Lists

Begin lines with "*", "+", or "-".

• unordered list item 1
• unordered list item 2

NOTE: To indent in a list add 4 spaces prior to the "*", "+", or "-".

• list item 1
  • indented item 1

Tables

Markdown can be used instead of HTML to create simple tables. Column headers go on the first line. The next line is a separator between the headers and the rows. Every other line is a row in the table. Columns must be separated by the pipe (|) character.

The following is an example of the code and how it appears once rendered.

Header 1  | Header 2
--------- | ---------
Content 1  | Content 3
Content 2  | Content 4

Adding Images

1. Upload the image to the KCS in question (Do not violate copyright laws by using unauthorized images, keep a worldwide perspective in mind as laws by Country may vary, and default to use Red Hat brand approved images.)
2. Once the image is uploaded you will see a link to that, click with right button to grab the link to the image
3. The syntax in markdown to add an image is:

 ![alt text](http://image_url)

More Information

For a more complete description of Markdown syntax, see http://daringfireball.net/projects/markdown/syntax and http://michelf.ca/projects/php-markdown/extra/.

NOTE: The markdown syntax described on these sites might differ slightly from the Markdown syntax used by the Red Hat Knowledgebase.

It is encouraged to test more advanced formatting before editing an article as some changes may result in losing the ability to continue editing an article and the only way forward is refreshing page losing all edits. For example see the note in line breaks.