Here, we break down the basic syntax for a markdown file. We also cover how to create and format markdown (.md) files.

About Markdown

Markdown is a human readable syntax for formatting text documents. Markdown can be used to produce nicely formatted documents including pdfs, web pages and more. When you format text using markdown in a document, it is similar to using the format tools (bold, heading 1, heading 2, etc) in a word processing tool like Microsoft Word or Google Docs.

Markdown Syntax in .Rmd Files

An R Markdown file can contain text written using the markdown syntax. Markdown text, can be whatever you want. It may describe the data that you are using, how it’s being processed and what the outputs are. You may even add some text that interprets or discusses the outputs.

When you render your document to html, this markdown will appear as text on the output html document. We will learn about the markdown syntax next.

Data Tip: This web page that you are reading right now is generated from a markdown document.

In this tutorial, we cover the basic syntax of markdown.

Markdown Syntax

Markdown is simple plain text, that is styled using special characters, including:

• ` #`: a header element.
• **: bold text.
• *: italic text.
• ` : code blocks.

Let’s review some basic markdown syntax.

Paragraph Text

When you type text in a markdown document with not additional syntax, the text will appear as paragraph text. You can add additional syntax to that text to format it in different ways.

For example, if we want to highlight a function or some code within a plain text paragraph, we can use one backtick on each side of the text ( `` ), like this: `Here is some code`. This is the backtick, or grave; not an apostrophe (on most US keyboards it is on the same key as the tilde (~)).

To add emphasis to other text you can use bold or italics.

Have a look at the markdown below:

The use of the highlight ( `text` ) will be reserved for denoting code.
To add emphasis to other text use **bold** or *italics*.

Notice that this sentence uses both a code highlight “``”, bold and italics. As a rendered markdown chunk, it looks like this:

The use of the highlight ( text ) will be reserve for denoting code when used in text. To add emphasis to other text use bold or italics.

Horizontal Lines (rules)

Create a rule:

  ***

Below is the rule rendered:

Section Headings

We create a heading using the pound (#) sign. For the headers to render properly there must be a space between the # and the header text. Heading one is 1 # sign, heading two is 2 ## signs, etc as follows:

Heading Two

## Heading Two

Heading Three

### Heading Three

Heading Four

#### Heading Four

Data tip: There are many free Markdown editors out there! The atom.io editor is a powerful text editor package by GitHub, that also has a Markdown renderer that allows you to preview the rendered Markdown as you write.

Explore Your R Markdown File

Look closely at the pre-populated markdown and R code chunks in the .Rmd file that we created above.

Does any of the markdown syntax look familiar?

• Are any words in bold?
• Are any words in italics?
• Are any words highlighted as code?

If you are unsure, the answers are at the bottom of this page.

Got questions? Leave your question in the comment box below. It’s likely some of your colleagues have the same question, too! And also likely someone else knows the answer.