Markdown Help

Updated -

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

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.1

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>

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


  1. Here is the actual footnote. Please note that the colon is required for the footnote syntax to work properly. ↩︎

16 Comments

Handy site for learning markdown: http://daringfireball.net/projects/markdown/dingus

This is a great tool, and help me a lot

It would be very useful if cpu spike and thread dump were intercepted automatically, because many benchmark are executed during the night...

When upgrade option is selected, what exactly are the steps done by the installer?
Instead of booting from DVD, I would like to do in-place upgrade from RHEL 5.5 to 6.2.
Is there a document on what all things to be taken care before and after upgrade?

This markup document is highly useful.

Please see Red Hat Discussion ID https://access.redhat.com/discussions/2080353. As of Dec 8th 2015, many of the Markdown (not HTML) features within this article are not working in the Red Hat Discussion area.

The following NOTE seems inaccurate:

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.

I tried both:

header {#tag}
============

and:

## header {#tag}

and both of them work just fine (at least in preview mode.)

I wonder, what implementation is portal using, so one can experiment and check content outside of portal.

The Line breaks section says:

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

In fact the line breaks are preserved regardless whether there are any spaces at the end of the line.

Seems the markdown implementation is somewhat non-conforming, broken or rather poorly documented. (I am playing with preview only, I would like to avoid having hundreds of revisions only to experiment with formatting.)

UPDATE: WARNING! This may completely break the UI when running preview. I have tried embedding SVG in a page, which resulted in mismatched tags and the UI to further edit or cancel editing was not rendered. I had to refresh the page losing all changes.

Attaching SVG file does not work: Allowed file types: jpg jpeg gif png doc docx txt xls xlsx pdf ppt pps odt ods odp tar gz tgz zip jar log bz c cpp py j csv bz2 xz sh stp xml rtf.

Seems almost anything else is supported. Is there a reason why SVG not? Can it be enabled, please?

Outside code block

this is code block

Outside code block

This is a markdown example inline link.

Is adding strikethrough formatting on the roadmap? (GitHub-flavored markdown has it.)

+1

From description of footnotes (note that blockquotes syntax is not working for the line below):

you cannot create two links to the same footnote

That's pretty prohibitive, I'd vote for removing this "just one pointer to a single footnote" restriction as it imposes needless redundancy (and we want compact and concise articles and what not, right?).

If you really want to reuse a footnote, you can do something like this:

 [<sup>1</sup>](#fn:1)

That will create a superscript 1 pointing to the 1st footnote.

For image

If you put something in "alt text", it will not display the image, and will only provide a text url

The only I have found to make it working is by removing the text using

Images should be do it like

[image=[src="images/openshift_life_cycle_30_0619_v4.png", alt="OCP v4 Life Cycle", size="LG - Large", data-cp-size="100%", data-cp-align="center", ]]