Overview
Nearly all Markdown applications support the basic syntax outlined in John Gruber’s original design document. There are minor variations and discrepancies between Markdown processors — those are noted inline wherever possible.
Headings
The inline code is to show code verbatim, not to 'interpret' that code. What you want is completely contradictory. So you have two options: 1. R markdownis a particular kind of markdown document. Authors should be cautious about following formatting advice for other types of markdown when working on R markdown. The distinguishing feature of R markdownis that it cooperates with R. Like LATEX with Sweave, code chunks can be included. When the document is compiled, the code is executed.
To create a heading, add number signs (
#
) in front of a word or phrase. The number of number signs you use should correspond to the heading level. For example, to create a heading level three (<h3>
), use three number signs (e.g., ### My Header
).Markdown | HTML | Rendered Output |
---|---|---|
# Heading level 1 | <h1>Heading level 1</h1> | |
## Heading level 2 | <h2>Heading level 2</h2> | Heading level 2 |
### Heading level 3 | <h3>Heading level 3</h3> | Heading level 3 |
#### Heading level 4 | <h4>Heading level 4</h4> | Heading level 4 |
##### Heading level 5 | <h5>Heading level 5</h5> | Heading level 5 |
###### Heading level 6 | <h6>Heading level 6</h6> | Heading level 6 |
Alternate Syntax
- Nearly all Markdown applications support the basic syntax outlined in John Gruber’s original design document. There are minor variations and discrepancies between Markdown processors — those are noted inline wherever possible. To create a heading, add number signs (#) in front of a word or phrase. The number of number signs you.
- Creating documents with R Markdown starts with an.Rmd file that contains a combination of markdown (content with simple text formatting) and R code chunks. The.Rmd file is fed to knitr, which executes all of the R code chunks and creates a new markdown (.md) document which includes the R.
- Markdown supports adding inline code like this, obtained by wrapping text in backticks: `code here` Alternatively, you can put your inline code between and HTML tags. Consider the following markdown code: `This` is an inline code block! This is one too! That would produce the following output: This is an inline code.
Alternatively, on the line below the text, add any number of characters for heading level 1 or
--
characters for heading level 2.Markdown | HTML | Rendered Output |
---|---|---|
Heading level 1 | <h1>Heading level 1</h1> | |
Heading level 2 | <h2>Heading level 2</h2> | Heading level 2 |
Heading Best Practices
Markdown applications don’t agree on how to handle a missing space between the number signs (
#
) and the heading name. For compatibility, always put a space between the number signs and the heading name.✅ Do this | ❌ Don't do this |
---|---|
# Here's a Heading | #Here's a Heading |
Paragraphs
To create paragraphs, use a blank line to separate one or more lines of text.
Markdown | HTML | Rendered Output |
---|---|---|
I really like using Markdown. | <p>I really like using Markdown.</p> | I really like using Markdown. I think I'll use it to format all of my documents from now on. |
Paragraph Best Practices
Unless the paragraph is in a list, don’t indent paragraphs with spaces or tabs.
✅ Do this | ❌ Don't do this |
---|---|
Don't put tabs or spaces in front of your paragraphs. | This can result in unexpected formatting problems. |
Line Breaks
To create a line break (
<br>
), end a line with two or more spaces, and then type return. Chalk paint brushes amazon.Markdown | HTML | Rendered Output |
---|---|---|
This is the first line. | <p>This is the first line.<br> | This is the first line. And this is the second line. |
Line Break Best Practices
You can use two or more spaces (commonly referred to as “trailing whitespace”) for line breaks in nearly every Markdown application, but it’s controversial. It’s hard to see trailing whitespace in an editor, and many people accidentally or intentionally put two spaces after every sentence. For this reason, you may want to use something other than trailing whitespace for line breaks. Fortunately, there is another option supported by nearly every Markdown application: the
<br>
HTML tag.For compatibility, use trailing white space or the
<br>
HTML tag at the end of the line.There are two other options I don’t recommend using. CommonMark and a few other lightweight markup languages let you type a backslash (
) at the end of the line, but not all Markdown applications support this, so it isn’t a great option from a compatibility perspective. And at least a couple lightweight markup languages don’t require anything at the end of the line — just type return and they’ll create a line break.✅ Do this | ❌ Don't do this |
---|---|
First line with two spaces after. | First line with a backslash after. |
Emphasis
You can add emphasis by making text bold or italic.
Bold
To bold text, add two asterisks or underscores before and after a word or phrase. To bold the middle of a word for emphasis, add two asterisks without spaces around the letters.
Markdown | HTML | Rendered Output |
---|---|---|
I just love **bold text**. | I just love <strong>bold text</strong>. | I just love bold text. |
I just love __bold text__. | I just love <strong>bold text</strong>. | I just love bold text. |
Love**is**bold | Love<strong>is</strong>bold | Loveisbold |
Bold Best Practices
Markdown applications don’t agree on how to handle underscores in the middle of a word. For compatibility, use asterisks to bold the middle of a word for emphasis.
✅ Do this | ❌ Don't do this |
---|---|
Love**is**bold | Love__is__bold |
Italic
To italicize text, add one asterisk or underscore before and after a word or phrase. To italicize the middle of a word for emphasis, add one asterisk without spaces around the letters.
Markdown | HTML | Rendered Output |
---|---|---|
Italicized text is the *cat's meow*. | Italicized text is the <em>cat's meow</em>. | Italicized text is the cat’s meow. |
Italicized text is the _cat's meow_. | Italicized text is the <em>cat's meow</em>. | Italicized text is the cat’s meow. |
A*cat*meow | A<em>cat</em>meow | Acatmeow |
Italic Best Practices
Markdown applications don’t agree on how to handle underscores in the middle of a word. For compatibility, use asterisks to italicize the middle of a word for emphasis.
✅ Do this | ❌ Don't do this |
---|---|
A*cat*meow | A_cat_meow |
R Markdown Inline Calculation
Bold and Italic
To emphasize text with bold and italics at the same time, add three asterisks or underscores before and after a word or phrase. To bold and italicize the middle of a word for emphasis, add three asterisks without spaces around the letters.
Markdown | HTML | Rendered Output |
---|---|---|
This text is ***really important***. | This text is <strong><em>really important</em></strong>. | This text is really important. |
This text is ___really important___. | This text is <strong><em>really important</em></strong>. | This text is really important. |
This text is __*really important*__. | This text is <strong><em>really important</em></strong>. | This text is really important. |
This text is **_really important_**. | This text is <strong><em>really important</em></strong>. | This text is really important. |
This is really***very***important text. | This is really<strong><em>very</em></strong>important text. | This is reallyveryimportant text. |
Bold and Italic Best Practices
Markdown applications don’t agree on how to handle underscores in the middle of a word. For compatibility, use asterisks to bold and italicize the middle of a word for emphasis.
✅ Do this | ❌ Don't do this |
---|---|
This is really***very***important text. | This is really___very___important text. |
Blockquotes
To create a blockquote, add a
>
in front of a paragraph.The rendered output looks like this:
Dorothy followed her through many of the beautiful rooms in her castle.
Blockquotes with Multiple Paragraphs
Blockquotes can contain multiple paragraphs. Add a
>
on the blank lines between the paragraphs.The rendered output looks like this:
Dorothy followed her through many of the beautiful rooms in her castle.
The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
Nested Blockquotes
Blockquotes can be nested. Add a
>>
in front of the paragraph you want to nest.The rendered output looks like this:
Dorothy followed her through many of the beautiful rooms in her castle.
The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
Blockquotes with Other Elements
Blockquotes can contain other Markdown formatted elements. Not all elements can be used — you’ll need to experiment to see which ones work.
The rendered output looks like this:
The quarterly results look great!
- Revenue was off the chart.
- Profits were higher than ever.
Everything is going according to plan.
Lists
You can organize items into ordered and unordered lists.
Ordered Lists
To create an ordered list, add line items with numbers followed by periods. The numbers don’t have to be in numerical order, but the list should start with the number one.
Markdown | HTML | Rendered Output |
---|---|---|
1. First item | <ol> |
|
1. First item | <ol> |
|
1. First item | <ol> |
|
1. First item | <ol> |
|
Ordered List Best Practices
CommonMark and a few other lightweight markup languages let you use a parenthesis (
)
) as a delimiter (e.g., 1) First item
), but not all Markdown applications support this, so it isn’t a great option from a compatibility perspective. For compatibility, use periods only.✅ Do this | ❌ Don't do this |
---|---|
1. First item | 1) First item |
Unordered Lists
To create an unordered list, add dashes (
-
), asterisks (*
), or plus signs (+
) in front of line items. Indent one or more items to create a nested list.Markdown | HTML | Rendered Output |
---|---|---|
- First item | <ul> |
|
* First item | <ul> |
|
+ First item | <ul> |
|
- First item | <ul> |
|
Starting Unordered List Items With Numbers
If you need to start an unordered list item with a number followed by a period, you can use a backslash (
) to escape the period.Markdown | HTML | Rendered Output |
---|---|---|
- 1968. A great year! | <ul> |
|
Unordered List Best Practices
Markdown applications don’t agree on how to handle different delimiters in the same list. For compatibility, don’t mix and match delimiters in the same list — pick one and stick with it.
✅ Do this | ❌ Don't do this |
---|---|
- First item | + First item |
Adding Elements in Lists
To add another element in a list while preserving the continuity of the list, indent the element four spaces or one tab, as shown in the following examples.
Paragraphs
The rendered output looks like this:
- This is the first list item.
- Here’s the second list item.I need to add another paragraph below the second list item.
- And here’s the third list item.
Blockquotes
The rendered output looks like this:
- This is the first list item.
- Here’s the second list item.A blockquote would look great below the second list item.
- And here’s the third list item.
Code Blocks
Code blocks are normally indented four spaces or one tab. When they’re in a list, indent them eight spaces or two tabs.
The rendered output looks like this:
- Open the file.
- Find the following code block on line 21:
- Update the title to match the name of your website.
Images
The rendered output looks like this:
- Open the file containing the Linux mascot.
- Marvel at its beauty.
- Close the file.
Lists
You can nest an unordered list in an ordered list, or vice versa.
The rendered output looks like this:
- First item
- Second item
- Third item
- Indented item
- Indented item
- Fourth item
Code
To denote a word or phrase as code, enclose it in backticks (
`
).Markdown | HTML | Rendered Output |
---|---|---|
At the command prompt, type `nano`. | At the command prompt, type <code>nano</code>. | At the command prompt, type nano . |
Escaping Backticks
If the word or phrase you want to denote as code includes one or more backticks, you can escape it by enclosing the word or phrase in double backticks (
``
).Markdown | HTML | Rendered Output |
---|---|---|
``Use `code` in your Markdown file.`` | <code>Use `code` in your Markdown file.</code> | Use `code` in your Markdown file. |
Code Blocks
To create code blocks, indent every line of the block by at least four spaces or one tab.
The rendered output looks like this:
Note: To create code blocks without indenting lines, use fenced code blocks.
Horizontal Rules
To create a horizontal rule, use three or more asterisks (
***
), dashes (---
), or underscores (___
) on a line by themselves.The rendered output of all three looks identical:
Horizontal Rule Best Practices
For compatibility, put blank lines before and after horizontal rules.
✅ Do this | ❌ Don't do this |
---|---|
Try to put a blank line before.. | Without blank lines, this would be a heading. |
Links
To create a link, enclose the link text in brackets (e.g.,
[Duck Duck Go]
) and then follow it immediately with the URL in parentheses (e.g., (https://duckduckgo.com)
). Animal crossing nintendo switch console.The rendered output looks like this:
My favorite search engine is Duck Duck Go.
Adding Titles
You can optionally add a title for a link. This will appear as a tooltip when the user hovers over the link. To add a title, enclose it in parentheses after the URL.
The rendered output looks like this:
My favorite search engine is Duck Duck Go.
URLs and Email Addresses
To quickly turn a URL or email address into a link, enclose it in angle brackets.
The rendered output looks like this:
https://www.markdownguide.org
[email protected]
[email protected]
Formatting Links
To emphasize links, add asterisks before and after the brackets and parentheses. To denote links as code, add backticks in the brackets.
The rendered output looks like this:
I love supporting the EFF.
This is the Markdown Guide.
See the section on
This is the Markdown Guide.
See the section on
code
.Reference-style Links
Reference-style links are a special kind of link that make URLs easier to display and read in Markdown. Reference-style links are constructed in two parts: the part you keep inline with your text and the part you store somewhere else in the file to keep the text easy to read.
Formatting the First Part of the Link
The first part of a reference-style link is formatted with two sets of brackets. The first set of brackets surrounds the text that should appear linked. The second set of brackets displays a label used to point to the link you’re storing elsewhere in your document.
Although not required, you can include a space between the first and second set of brackets. The label in the second set of brackets is not case sensitive and can include letters, numbers, spaces, or punctuation.
This means the following example formats are roughly equivalent for the first part of the link:
[hobbit-hole][1]
[hobbit-hole] [1]
Formatting the Second Part of the Link
The second part of a reference-style link is formatted with the following attributes:
- The label, in brackets, followed immediately by a colon and at least one space (e.g.,
[label]:
). - The URL for the link, which you can optionally enclose in angle brackets.
- The optional title for the link, which you can enclose in double quotes, single quotes, or parentheses.
This means the following example formats are all roughly equivalent for the second part of the link:
[1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle
[1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle 'Hobbit lifestyles'
[1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle 'Hobbit lifestyles'
[1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle (Hobbit lifestyles)
[1]: <https://en.wikipedia.org/wiki/Hobbit#Lifestyle> 'Hobbit lifestyles'
[1]: <https://en.wikipedia.org/wiki/Hobbit#Lifestyle> 'Hobbit lifestyles'
[1]: <https://en.wikipedia.org/wiki/Hobbit#Lifestyle> (Hobbit lifestyles)
You can place this second part of the link anywhere in your Markdown document. Some people place them immediately after the paragraph in which they appear while other people place them at the end of the document (like endnotes or footnotes).
An Example Putting the Parts Together
Say you add a URL as a standard URL link to a paragraph and it looks like this in Markdown:
Though it may point to interesting additional information, the URL as displayed really doesn’t add much to the existing raw text other than making it harder to read. To fix that, you could format the URL like this instead:
In both instances above, the rendered output would be identical:
In a hole in the ground there lived a hobbit. Not a nasty, dirty, wet hole, filled with the ends of worms and an oozy smell, nor yet a dry, bare, sandy hole with nothing in it to sit down on or to eat: it was a hobbit-hole, and that means comfort.
and the HTML for the link would be:
Link Best Practices
Markdown applications don’t agree on how to handle spaces in the middle of a URL. For compatibility, try to URL encode any spaces with
%20
.✅ Do this | ❌ Don't do this |
---|---|
[link](https://www.example.com/my%20great%20page) | [link](https://www.example.com/my great page) |
Images
To add an image, add an exclamation mark (
!
), followed by alt text in brackets, and the path or URL to the image asset in parentheses. You can optionally add a title after the URL in the parentheses.The rendered output looks like this:
![R Markdown Inline R Markdown Inline](/uploads/1/1/7/8/117804713/154167463.png)
Linking Images
To add a link to an image, enclose the Markdown for the image in brackets, and then add the link in parentheses.
The rendered output looks like this:
Escaping Characters
To display a literal character that would otherwise be used to format text in a Markdown document, add a backslash (
) in front of the character.The rendered output looks like this:
* Without the backslash, this would be a bullet in an unordered list.
Characters You Can Escape
You can use a backslash to escape the following characters.
Character | Name |
---|---|
backslash | |
` | backtick (see also escaping backticks in code) |
* | asterisk |
_ | underscore |
{ } | curly braces |
[ ] | brackets |
< > | angle brackets |
( ) | parentheses |
# | pound sign |
+ | plus sign |
- | minus sign (hyphen) |
. | dot |
! | exclamation mark |
| | pipe (see also escaping pipe in tables) |
HTML
Many Markdown applications allow you to use HTML tags in Markdown-formatted text. This is helpful if you prefer certain HTML tags to Markdown syntax. For example, some people find it easier to use HTML tags for images. Using HTML is also helpful when you need to change the attributes of an element, like specifying the color of text or changing the width of an image.
To use HTML, place the tags in the text of your Markdown-formatted file.
The rendered output looks like this:
This word is bold. This word is italic.
HTML Best Practices
For security reasons, not all Markdown applications support HTML in Markdown documents. When in doubt, check your Markdown application’s documentation. Some applications support only a subset of HTML tags.
Use blank lines to separate block-level HTML elements like
<div>
, <table>
, <pre>
, and <p>
from the surrounding content. Try not to indent the tags with tabs or spaces — that can interfere with the formatting.You can’t use Markdown syntax inside block-level HTML tags. For example,
<p>italic and **bold**</p>
won’t work.Take your Markdown skills to the next level.
Learn Markdown in 60 pages. Designed for both novices and experts, The Markdown Guide book is a comprehensive reference that has everything you need to get started and master Markdown syntax.
Get the BookWant to learn more Markdown?
Don't stop now! ? Star the GitHub repository and then enter your email address below to receive new Markdown tutorials via email. No spam!
NOTE: R Notebooks are new feature of RStudio and are only available in version 1.0 or higher of RStudio. You can download the latest version of RStudio here: https://www.rstudio.com/products/rstudio/download/.
Overview
An R Notebook is an R Markdown document with chunks that can be executed independently and interactively, with output visible immediately beneath the input.
R Notebooks are a method of literate programming that allows for direct interaction with R while producing a reproducible document with publication-quality output.
Any R Markdown document can be used as a notebook, and all R Notebooks can be rendered to other R Markdown document types. A notebook can therefore be thought of as a special execution mode for R Markdown documents. The immediacy of notebook mode makes it a good choice while authoring the R Markdown document and iterating on code; when you are ready to publish the document, you can share the notebook directly, or render it to a publication format with the Knit command.
Using Notebooks
Creating a Notebook
You can create a new notebook in RStudio with the menu command File -> New File -> R Notebook, or by using the
html_notebook
output type in your document’s YAML header.By default, RStudio enables inline output (notebook mode) on all R Markdown documents, so you can interact with any R Markdown document as though it were a notebook. If you have a document with which you prefer to use the traditional console method of interaction, you can disable notebook mode by clicking the gear in the editor toolbar and choosing Chunk Output in Console.
If you prefer to use the console by default for all your R Markdown documents (restoring the behavior in previous versions of RStudio), you can make Chunk Output in Console the default: Tools -> Options -> R Markdown -> Show output inline for all R Markdown documents.
Inserting Chunks
Notebook chunks can be inserted quickly using the keyboard shortcut Ctrl + Alt + I (OS X: Cmd + Option + I), or via the Add Chunk command in the editor toolbar.
Because all of a chunk’s output appears beneath the chunk (not alongside the statement which emitted the output, as it does in rendered R Markdown output), it’s often helpful to split chunks that produce multiple outputs into two or more chunks which each produce only one output. To do this, select the code to split into a new chunk:
Then, press Ctrl + Alt + I (OS X: Cmd + Option + I):
Executing Code
Code in the notebook is executed with the same gestures you’d use to execute code in an R Markdown document:
- Use the Run Chunk command, or Ctrl + Shift * Enter (OS X: Cmd + Shift + Enter) to run the current chunk.
- Press Ctrl + Enter (OS X: Cmd + Enter) to run just the current statement. Running a single statement is much like running an entire chunk consisting only of that statement (see notes below on the chunk execution environment).
- Use the Run All and Run Previous commands to run a batch of chunks.
The primary difference is that when executing chunks in an R Markdown document, all the code is sent to the console at once, but in a notebook, only one line at a time is sent. This allows execution to stop if a line raises an error (see notes below on handling errors).
There’s also a new Restart R and Run All Chunks command (available in the Run menu on the editor toolbar), which gives you a fresh R session prior to running all the chunks. This behavior is similar to the Knit command, which in RStudio occurs in a separate R session.
Execution Queue
When you execute code in a notebook, an indicator will appear in the gutter to show you execution progress.
Lines of code which have been sent to R are marked with dark green; lines which have not yet been sent to R are marked with light green.
If at least one chunk is waiting to be executed, you’ll see a progress meter appear in the editor’s status bar indicating the number of chunks remaining to be executed. You can click on this meter at any time to jump to the currently executing chunk.
When a chunk is waiting to execute, the Run button in its toolbar will change to a Queued icon. If you don’t want the chunk to run, you can click on the Queued icon to remove it from the execution queue.
Execution Environment
In general, when you execute code in a notebook chunk, it will do exactly the same thing as it would if that same code were typed into the console. There are however a few differences:
Output: The most obvious difference is that most forms of output produced from a notebook chunk are shown in the chunk output rather than e.g. the Viewer or Plots pane. Console output (including warnings and messages) appears both at the console and in the chunk output.
Working directory: The current working directory inside a notebook chunk is always the directory containing the notebook .Rmd file. This makes it easier to use relative paths inside notebook chunks, and also matches the behavior when knitting, making it easier to write code that works identically both interactively and in a standalone render.
You’ll get a warning if you try to change the working directory inside a notebook chunk, and the directory will revert back to the notebook’s directory once the chunk is finished executing. You can suppress this warning by using the
warnings = FALSE
chunk option.If it’s necessary to execute notebook chunks in a different directory, you can change the working directory for all your chunks by using the knitr
root.dir
option. For instance, to execute all notebook chunks in the grandparent folder of the notebook:This option is only effective when used inside the setup chunk. Note also that, as in knitr, the
root.dir
chunk option applies only to chunks; relative paths in Markdown are still relative to the notebook’s parent folder.Warnings: Inside a notebook chunk, warnings are always displayed immediately rather than being held until the end, as in
options(warn = 1)
.Plots: Plots emitted from a chunk are rendered to match the width of the editor at the time the chunk was executed. The height of the plot is determined by the golden ratio. The plot’s display list is saved, too, and the plot is re-rendered to match the editor’s width when the editor is resized.
You can use the
fig.width
, fig.height
, and fig.asp
chunk options to manually specify the size of rendered plots in the notebook; you can also use knitr::opts_chunk$set(fig.width = .., fig.height = ..)
in the setup chunk to to set a default rendered size. Note however specifying a chunk size manually suppresses the generation of the display list, so plots with manually specified sizes will be resized using simple image scaling when the notebook editor is resized.Executing Inline Chunks
R Markdown Inline Variable
Teams link opens with browser. An inline chunk is a chunk which is inline with the text rather than on its own line. For instance, “2 + 2 =
`r 2 + 2`
” will be rendered as “2 + 2 = 4”.To execute an inline chunk in the notebook, put your cursor inside the chunk and press Ctrl + Shift + Enter (OS X: Cmd + Shift + Enter). As in the execution of ordinary chunks, the content of the chunk will be sent to the R console for evaluation. The results will appear in a small pop-up window next to the code:
In notebooks, inline R chunks can only produce text, not figures or other kinds of output. It’s also important that R code run inside inline chunks executes quickly and does not have side effects, as it’s executed whenever you save the notebook.
Executing External Chunks
Notebooks are typically self-contained. However, in some situations it’s preferable to re-use code from an R script as a notebook chunk, as in knitr’s code externalization. This can be done by using
knitr::read_chunk
in your notebook’s setup chunk, along with a special ## ---- chunkname
annotation in the R file from which you intend to read code. Here is a minimal example:example.Rmd
example.R
When you execute the empty chunk in the notebook, code from the external file will be inserted, and the results displayed inline, as though the chunk contained that code.
Chunk Output
Managing Output
When code is executed in the notebook, its output appears beneath the code chunk that produced it. You can clear an individual chunk’s output by clicking the X in the upper right corner of the output, or collapse it by clicking the chevron.
It’s also possible to clear or collapse all of the output in the document at once using the Collapse All Output and Clear All Output commands; these commands are available on the gear menu in the editor toolbar.
If you want to fully reset the state of the notebook, the command Restart R and Clear All Output will do the job.
See Output Storage below for more information on where chunk output is saved.
Previewing Output
Ordinary R Markdown documents are “knit”, but notebooks are “previewed”. While the notebook preview looks similar to a rendered R Markdown document, the notebook preview does not execute any of your R code chunks; it simply shows you a rendered copy of the markdown in your document along with the most recent chunk output. This preview is generated automatically whenever you save the notebook (whether you are viewing it in RStudio or not); see the section beneath on the .nb.html file for details.
When
html_notebook
is the topmost (default) format in your YAML header, you’ll see a Preview button in the editor toolbar. Clicking it will show you the notebook preview:If you have configured R Markdown previewing to use the Viewer pane (as illustrated above) then the preview will be automatically updated whenever you save your notebook.
Handling Errors
When an error occurs while a notebook chunk is executing:
- Execution will stop; the remaining lines of that chunk (and any chunks that have not yet been run) will not be executed.
- The editor will scroll to the error.
- The line of code that caused the error will have a red indicator in the editor’s gutter.
If you want your notebook to keep running after an error, you can suppress the first two behaviors by specifying
errors = TRUE
in the chunk options.Console Hiding
In most cases it shouldn’t be necessary to have the console open while using the notebook, as you can see all of the console output in the notebook itself. To preserve vertical space, the console will be automatically collapsed when you open a notebook or run a chunk in the notebook.
If you prefer not to have the console hidden when chunks are executed, uncheck Tools -> Global Options -> R Markdown -> Hide console automatically when executing notebook chunks.
Saving and Sharing
Notebook File
R Markdown Inline Latex
When a notebook .Rmd is saved, an
.nb.html
file is created alongside it. This file is a self-contained HTML file which contains both a rendered copy of the notebook with all current chunk outputs (suitable for display on a website) and a copy of the notebook .Rmd itself.You can view the
.nb.html
file in any ordinary web browser. It can also be opened in RStudio; when you open there (using e.g. File -> Open), RStudio will do the following:R Markdown Tutorial
- Extract the bundled .Rmd file and place it alongside the .nb.html file
- Open the .Rmd file in a new RStudio editor tab
- Extract the chunk outputs from the
.nb.html
file and place them appropriately in the editor
Note that the
.nb.html
file is only created for R Markdown documents which are notebooks (i.e. at least one of their output formats is html_notebook
). It’s possible to have an R Markdown document which includes inline chunk output but does not produce an .nb.html
file.Markdown Inline Code Highlighting
Output Storage
The document’s chunk outputs are also stored in an internal RStudio folder beneath the project’s
.Rproj.user
folder. If you work with a notebook but don’t have a project open, the outputs are stored in the RStudio state folder in your home directory (the location of this folder varies between the desktop and the server).Version Control
One of the major advantages of R Notebooks compared to other notebook systems is that they are plain-text files and therefore work well with version control. We recommend checking in both the .Rmd and .nb.html files into version control so that both your source code and output are available to collaborators. However, you can choose to include only the .Rmd file (with a
.gitignore
that excludes the .nb.html) if you want each collaborator to work with their own private copies of the output.Notebook Format
While RStudio provides a set of integrated tools for authoring R Notebooks, the notebook file format itself is decoupled from RStudio. The rmarkdown package provides several functions that can be used to read and write R Notebooks outside of RStudio.
R Markdown Inline Equation
You can find documentation for these functions and additional information on the
.nb.html
file format in the R Notebook HTML Format article.