Nothing
In memoiR: R Markdown and Bookdown Templates to Publish Documents
Syntax
```{block, type='Summary'}
Deliver the take-home message here.
It can contain several paragraphs.
The syntax of _R Mardown_ extended by _Bookdown_ is recalled here.
In RStudio, create a new document of type Document R Markdown.
The wizard allows you to choose between different formats.
Click on _From template_: from templates installed by packages.
The memoiR package templates are displayed: choose *Memoir*.
Each chapter of the book is an Rmd file, whose name normally starts with its number (e.g. `01-intro.Rmd`).
All Rmd files in the project folder are actually treated as chapters, sorted by file name, including those provided by the template (startup and syntax) which should be deleted except for `99-references.Rmd` which contains the bibliography, placed at the end.
The `index.Rmd` file is special: it contains the document header and the first chapter.
Each other file starts with a top-level title:
Title of the Chapter
If the document is made of parts containing chapters, the file with the fist chapter of each part must start with:
(PART) Title of the Part {-}
Title of the Chapter
Note the `{-}` instruction after the title of the part to avoid having it numbered.
Appendices are introduced as a special part:
(APPENDIX) Appendix {-}
Title of the first appendix
## Write
The main features of Markdown are summarized here.
A quick and complete training is offered by RStudio[^821].
[^821]: https://rmarkdown.rstudio.com/lesson-1.html
The text is written without any formatting other than line breaks.
A simple line break has no effect on the document produced: it allows to separate sentences to simplify the tracking of the source code by git.
A line break marks a paragraph change.
The different levels of the plan are designated by the number of braces at the beginning of the line: `#` for a level 1 title, `##` for a level 2 title, etc.
A space separates the hashes and the title text.
Bullet lists are marked by a dash (followed by a space) at the beginning of the line.
An empty line is required before the beginning of the list, but the elements of the list are separated by a simple line break.
Indented lists are created by inserting 4 spaces before the dash at the beginning of the line.
Last, numbered lists are created in the same way by replacing the hyphens by numbers, whose value does not matter.
In the text, the italicized parts are surrounded by a star or an underscore (`*italic*`), while two stars mark the bold.
## R code
R code is included in code chunks (*code chunks*) that are easily created by clicking on the "Insert a new code chunk" button above the source code window in RStudio.
They start and end with three quotation marks on a new line.
These code chunks can contain R code but also Python code for example: the type of code is indicated in the header on the first line, before the name of the code chunk, then a comma separated list of options, for example:
````
```r`r ''`
The name and options are optional: the minimum header is `{r}`.
The most useful options are:
- `echo` to show (`=TRUE`) or hide (`=FALSE`) the code.
- `message=FALSE` to hide the opening messages of some packages.
- `warning=FALSE` to hide warnings.
The default options are declared in the code snippet named "Options" at the beginning of the Markdown document, in the `opts_chunk$set()` function.
The `echo` option should be set to `FALSE` by default for a scientific article for example.
When it is `TRUE`, the code is printed as follows
```r
2+2
```
## Figures
```r
plot(pressure)
```
Figures can be created by the R code (figure \@ref(fig:pressure)).
With Bookdown, a label is associated with each figure: its name is `fig:xxx` where `xxx` is the name of the R code snippet.
References are made with the command `\@ref(fig:xxx)`.
The header of the code snippet of the figure \@ref(fig:pressure) is:
``rr ''`
````
It contains at least the name of the figure and its caption.
The default width of figures is set in the option chunk in `index.Rmd`.
It is `out.width='80%'` in this template, i.e. 80% of the width of the text.
If a full-width figure is needed, including the margin width, use `out.width='\\widthw'` in its code chunk header.
When large margins are used in memoirs, figure captions are set in the margins of PDF outputs.
Margins can be used to enlarge a figure: add knitr options `out.width='\\widthw'` and `fig.env='figure'` in the code chunk header.
Figure alignment must be `fig.align = 'center'` (which is by default).
The caption is then inserted below the figure.
Small figures can be put in the margin by the option `fig.env='marginfigure'`.
These changes are ignored in the HTML output.
If the caption is long, the header is not easy to read.
Also, the caption is limited to simple text.
For more elaborate captions, it is possible to declare the caption in a separate paragraph that begins with the text `(ref:FigureName)`.
The figure \@ref(fig:pressure2) benefits from an improved caption.
(ref:pressure2) Title with _italic_, math ($\sqrt\pi$) and reference to figure \@ref(fig:pressure)
```r
plot(pressure)
The text in fig.cap, "Title of figure" previously, is replaced by (ref:pressure) within the quotation marks and the caption is entered in a paragraph starting with (ref:pressure) followed by a space.
Captions are limited to a single paragraph.
They should not contain bibliographic references or references to the figures may not find them: if necessary, cite the source of a figure in the text.
Figures that are not created by R but come from files are embedded in a piece of code by the include_graphics() function whose argument is the file containing the image to be displayed.
Always place these files in the images folder for good organization.
Tables
The horizontal - and vertical separators | allow to draw a table according to the Markdown syntax, but it is not the best method.
Tables can also be produced by R code.
The content of the table is in a dataframe.
The kable function in the knitr package prepares the table for display and passes the result to the kable_styling function in the kableExtra package for final formatting.
library("tidyverse")
names(iris) <- c("Sepal length ($l_s$)", "Width", "Petal length", "Width", "Species")
knitr::kable(head(iris), caption="Table created by R", booktabs = TRUE, escape = FALSE) %>%
kableExtra::kable_styling(bootstrap_options = "striped", full_width = FALSE)
The caption is specified by the caption argument and referencing is possible because the table is given a label whose name is tab: followed by the name of the code snippet (table \@ref(tab:kable)).
As with figures, an enhanced legend can be written in a separate paragraph.
Always use the booktabs = TRUE argument so that the thickness of the separator lines is optimal in LaTeX.
Since the table contains mathematics (in the name of the first column), the escape = FALSE option is necessary.
The bootstrap_options = "striped" style option provides more readable tables in HTML.
Last, the full_width = FALSE option allows you to adjust the width of the table to its content instead of occupying all the available width.
Maths
Equations in LaTeX format can be inserted in line, like $A=\pi r^2$ (code: $A=\pi r^2$) or isolated (the $ are doubled) like $$e^{i \pi} = -1.$$
They can be numbered: see equation \@ref(eq:disk), using the \equation environment.
\begin{equation}
A = \pi r^2.
(#eq:disk)
\end{equation}
The numbered equation is created by the following code:
\begin{equation}
A = \pi r^2.
(\#eq:disk)
\end{equation}
Cross-references
Figures and tables have an automatically generated label, identical to the name of the code snippet prefixed with fig: and tab:.
For equations, the label is added manually by the code (\#eq:xxx) before the end of the equation.
Sections can be tagged by ending their title with {#yyy}.
In all cases, the call to the reference is made by the command \@ref().
Bibliography
Bibliographic references in bibtex format must be included in the .bib file declared in the header of the Markdown document.
bibliography: references.bib
They can be called in the text, between brackets by the code [@CitationKey], as sidenotes [@Xie2016], or without square brackets, to include the authors' names in the text, such as @Xie2018 .
Bibliography is handled by pandoc when producing Word or HTML documents.
The bibliographic style can be specified, by adding the line
csl:file_name.csl
in the document header and copying the .csl style file into the project folder.
The default style (if no csl is specified) is "chicago-author-date".
Several thousand styles are available ^822.
For PDF documents, the bibliography is handled by BibLaTeX, see section \@ref(index).
Forcing line breaks
Hyphenation is handled automatically in LaTeX.
If a word is not hyphenated correctly, add its hyphenation in the preamble of the file with the command hyphenation (words are separated by spaces, hyphenation locations are represented by dashes).
If LaTeX can't find a solution for the line break, for example because some code is too long a non-breaking block, add the LaTeX command \break to the line break location.
Do not leave a space before the command.
The HTML document ignores LaTeX commands.
Languages {#sec:languages}
Languages are declared in the document header.
The main language of the document (lang) changes the name of some elements, such as the table of contents.
The change of language in the document (one of otherlangs) is managed in LaTeX but not in HTML by inserting on a new line the following command:
\selectlanguage{english}
The current language has an effect only in LaTeX output: a space is added before double punctuation in French, the size of spaces is larger at the beginning of sentences in English, etc.
The \selectlanguage command is simply ignored in HTML.
Language codes are used in the header, such as en-US but language names are necessary in \selectlanguage{}.
Name matches are listed in table 3 of the polyglossia package documentation^823.
Chapter summary
The take-home message of each chapter can be displayed in a box, see the beginning of this one.
The code is that of a code block of type "Summary".
```{block, type='Summary'}`r ''`
Some text for this block.
```
Its heading text is set in the header of index.Rmd:
chaptersummary: In a Nutshell
Local table of contents
At the beginning of each chapter of the PDF document, a local table of content can be added with the following code:
\toc{1}
It is ignored in HTML.
1 is the depth of the table of contents: sections of the chapters are included.
It can be changed for 2 to display subsections too, and so on.
Boxed text
Boxed text allows summarizing important points out of the main text.
An example is given here, to define the Pythagorean theorem.
(ref:pythbox) Pythagorean theorem
:::{#pythbox .greybox data-latex='[frametitle=(ref:pythbox)]' title='(ref:pythbox)'}
For a right triangle, if $c$ denotes the length of the hypotenuse
and $a$ and $b$ denote the lengths of the other two sides, we have
$$a^2 + b^2 = c^2$$
:::
These boxes are included in the document as fenced blocks, whose syntax is as follows:
title='Pythagorean theorem'}
For a right triangle, if $c$ denotes the length of the hypotenuse
and $a$ and $b$ denote the lengths of the other two sides, we have
$$a^2 + b^2 = c^3$$
:::
The text block is delimited by ::: instead of the backquotes of code chunks.
The header of the block contains its name, prefixed by #.
The type of block follows, here: .greybox.
Arguments data-latex and title contain the title of the box in the PDF and HTML outputs, so a referenced text caption is useful to avoid repeating it.
Enter it in a paragraph starting with (ref:pythbox) followed by a space.
Then, call the text with the code (ref:pythbox).
This technique is identical to that used for elaborate figure captions.
Note the particular syntax of the title in the PDF output.
Grey text boxes (.greybox) are provided by the memoir template.
Advanced users can define other colored boxes, say a yellow box, following the next steps:
- Obtain the HTML code of the color, for instance with a color picker^824.
ffff66 is suitable for yellow.
- In
latex/preamble.tex, define the color by adding the following line below the definition of the grey color:
\definecolor{yellow}{HTML}{FFFF66}
- Also define the text box environment by duplicating the
greybox item and replacing grey with yellow three times:
\newmdenv[
style=boxstyle,
backgroundcolor=yellow,
frametitlebackgroundcolor=yellow,
]{yellowbox}
- In
style.css, duplicate all lines that define "Grey text box", including the starting and ending comment lines.
Replace .greybox with .yellowbox everywhere, "Grey" with "Yellow" in the comments and change the background-color with #ffff66.
- In the text, use the same syntax as above but declare the class of the fenced block as
.yellowbox instead of .greybox.
Documentation
User documentation
- The book bookdown: Authoring Books and Technical Documents with R Markdown by Yihui Xie, the author of bookdown and knitr.
All the necessary details for writing (writing equations, cross-references, etc.) are given.
- The R Markdown cheat sheet for the syntax.
Documentation for developers
- LaTeX file format customization.
- The Pandoc manual for possible options in the YAML header.
Try the memoiR package in your browser
Any scripts or data that you put into this service are public.
memoiR documentation built on Sept. 14, 2023, 5:06 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Syntax
```{block, type='Summary'} Deliver the take-home message here.
It can contain several paragraphs.
The syntax of _R Mardown_ extended by _Bookdown_ is recalled here. In RStudio, create a new document of type Document R Markdown. The wizard allows you to choose between different formats. Click on _From template_: from templates installed by packages. The memoiR package templates are displayed: choose *Memoir*. Each chapter of the book is an Rmd file, whose name normally starts with its number (e.g. `01-intro.Rmd`). All Rmd files in the project folder are actually treated as chapters, sorted by file name, including those provided by the template (startup and syntax) which should be deleted except for `99-references.Rmd` which contains the bibliography, placed at the end. The `index.Rmd` file is special: it contains the document header and the first chapter. Each other file starts with a top-level title:
Title of the Chapter
If the document is made of parts containing chapters, the file with the fist chapter of each part must start with:
(PART) Title of the Part {-}
Title of the Chapter
Note the `{-}` instruction after the title of the part to avoid having it numbered.
Appendices are introduced as a special part:
(APPENDIX) Appendix {-}
Title of the first appendix
## Write The main features of Markdown are summarized here. A quick and complete training is offered by RStudio[^821]. [^821]: https://rmarkdown.rstudio.com/lesson-1.html The text is written without any formatting other than line breaks. A simple line break has no effect on the document produced: it allows to separate sentences to simplify the tracking of the source code by git. A line break marks a paragraph change. The different levels of the plan are designated by the number of braces at the beginning of the line: `#` for a level 1 title, `##` for a level 2 title, etc. A space separates the hashes and the title text. Bullet lists are marked by a dash (followed by a space) at the beginning of the line. An empty line is required before the beginning of the list, but the elements of the list are separated by a simple line break. Indented lists are created by inserting 4 spaces before the dash at the beginning of the line. Last, numbered lists are created in the same way by replacing the hyphens by numbers, whose value does not matter. In the text, the italicized parts are surrounded by a star or an underscore (`*italic*`), while two stars mark the bold. ## R code R code is included in code chunks (*code chunks*) that are easily created by clicking on the "Insert a new code chunk" button above the source code window in RStudio. They start and end with three quotation marks on a new line. These code chunks can contain R code but also Python code for example: the type of code is indicated in the header on the first line, before the name of the code chunk, then a comma separated list of options, for example: ```` ```r`r ''`
The name and options are optional: the minimum header is `{r}`.
The most useful options are:
- `echo` to show (`=TRUE`) or hide (`=FALSE`) the code.
- `message=FALSE` to hide the opening messages of some packages.
- `warning=FALSE` to hide warnings.
The default options are declared in the code snippet named "Options" at the beginning of the Markdown document, in the `opts_chunk$set()` function.
The `echo` option should be set to `FALSE` by default for a scientific article for example.
When it is `TRUE`, the code is printed as follows
```r
2+2
```
## Figures
```r
plot(pressure)
```
Figures can be created by the R code (figure \@ref(fig:pressure)).
With Bookdown, a label is associated with each figure: its name is `fig:xxx` where `xxx` is the name of the R code snippet.
References are made with the command `\@ref(fig:xxx)`.
The header of the code snippet of the figure \@ref(fig:pressure) is:
``rr ''`
```` It contains at least the name of the figure and its caption. The default width of figures is set in the option chunk in `index.Rmd`. It is `out.width='80%'` in this template, i.e. 80% of the width of the text. If a full-width figure is needed, including the margin width, use `out.width='\\widthw'` in its code chunk header. When large margins are used in memoirs, figure captions are set in the margins of PDF outputs. Margins can be used to enlarge a figure: add knitr options `out.width='\\widthw'` and `fig.env='figure'` in the code chunk header. Figure alignment must be `fig.align = 'center'` (which is by default). The caption is then inserted below the figure. Small figures can be put in the margin by the option `fig.env='marginfigure'`. These changes are ignored in the HTML output. If the caption is long, the header is not easy to read. Also, the caption is limited to simple text. For more elaborate captions, it is possible to declare the caption in a separate paragraph that begins with the text `(ref:FigureName)`. The figure \@ref(fig:pressure2) benefits from an improved caption. (ref:pressure2) Title with _italic_, math ($\sqrt\pi$) and reference to figure \@ref(fig:pressure) ```r plot(pressure)
The text in fig.cap, "Title of figure" previously, is replaced by (ref:pressure) within the quotation marks and the caption is entered in a paragraph starting with (ref:pressure) followed by a space.
Captions are limited to a single paragraph.
They should not contain bibliographic references or references to the figures may not find them: if necessary, cite the source of a figure in the text.
Figures that are not created by R but come from files are embedded in a piece of code by the include_graphics() function whose argument is the file containing the image to be displayed.
Always place these files in the images folder for good organization.
Tables
The horizontal - and vertical separators | allow to draw a table according to the Markdown syntax, but it is not the best method.
Tables can also be produced by R code.
The content of the table is in a dataframe.
The kable function in the knitr package prepares the table for display and passes the result to the kable_styling function in the kableExtra package for final formatting.
library("tidyverse") names(iris) <- c("Sepal length ($l_s$)", "Width", "Petal length", "Width", "Species") knitr::kable(head(iris), caption="Table created by R", booktabs = TRUE, escape = FALSE) %>% kableExtra::kable_styling(bootstrap_options = "striped", full_width = FALSE)
The caption is specified by the caption argument and referencing is possible because the table is given a label whose name is tab: followed by the name of the code snippet (table \@ref(tab:kable)).
As with figures, an enhanced legend can be written in a separate paragraph.
Always use the booktabs = TRUE argument so that the thickness of the separator lines is optimal in LaTeX.
Since the table contains mathematics (in the name of the first column), the escape = FALSE option is necessary.
The bootstrap_options = "striped" style option provides more readable tables in HTML.
Last, the full_width = FALSE option allows you to adjust the width of the table to its content instead of occupying all the available width.
Maths
Equations in LaTeX format can be inserted in line, like $A=\pi r^2$ (code: $A=\pi r^2$) or isolated (the $ are doubled) like $$e^{i \pi} = -1.$$
They can be numbered: see equation \@ref(eq:disk), using the \equation environment.
\begin{equation} A = \pi r^2. (#eq:disk) \end{equation}
The numbered equation is created by the following code:
\begin{equation}
A = \pi r^2.
(\#eq:disk)
\end{equation}
Cross-references
Figures and tables have an automatically generated label, identical to the name of the code snippet prefixed with fig: and tab:.
For equations, the label is added manually by the code (\#eq:xxx) before the end of the equation.
Sections can be tagged by ending their title with {#yyy}.
In all cases, the call to the reference is made by the command \@ref().
Bibliography
Bibliographic references in bibtex format must be included in the .bib file declared in the header of the Markdown document.
bibliography: references.bib
They can be called in the text, between brackets by the code [@CitationKey], as sidenotes [@Xie2016], or without square brackets, to include the authors' names in the text, such as @Xie2018 .
Bibliography is handled by pandoc when producing Word or HTML documents. The bibliographic style can be specified, by adding the line
csl:file_name.csl
in the document header and copying the .csl style file into the project folder. The default style (if no csl is specified) is "chicago-author-date". Several thousand styles are available ^822.
For PDF documents, the bibliography is handled by BibLaTeX, see section \@ref(index).
Forcing line breaks
Hyphenation is handled automatically in LaTeX.
If a word is not hyphenated correctly, add its hyphenation in the preamble of the file with the command hyphenation (words are separated by spaces, hyphenation locations are represented by dashes).
If LaTeX can't find a solution for the line break, for example because some code is too long a non-breaking block, add the LaTeX command \break to the line break location.
Do not leave a space before the command.
The HTML document ignores LaTeX commands.
Languages {#sec:languages}
Languages are declared in the document header.
The main language of the document (lang) changes the name of some elements, such as the table of contents.
The change of language in the document (one of otherlangs) is managed in LaTeX but not in HTML by inserting on a new line the following command:
\selectlanguage{english}
The current language has an effect only in LaTeX output: a space is added before double punctuation in French, the size of spaces is larger at the beginning of sentences in English, etc.
The \selectlanguage command is simply ignored in HTML.
Language codes are used in the header, such as en-US but language names are necessary in \selectlanguage{}.
Name matches are listed in table 3 of the polyglossia package documentation^823.
Chapter summary
The take-home message of each chapter can be displayed in a box, see the beginning of this one. The code is that of a code block of type "Summary".
```{block, type='Summary'}`r ''`
Some text for this block.
```
Its heading text is set in the header of index.Rmd:
chaptersummary: In a Nutshell
Local table of contents
At the beginning of each chapter of the PDF document, a local table of content can be added with the following code:
\toc{1}
It is ignored in HTML. 1 is the depth of the table of contents: sections of the chapters are included. It can be changed for 2 to display subsections too, and so on.
Boxed text
Boxed text allows summarizing important points out of the main text. An example is given here, to define the Pythagorean theorem.
(ref:pythbox) Pythagorean theorem
:::{#pythbox .greybox data-latex='[frametitle=(ref:pythbox)]' title='(ref:pythbox)'} For a right triangle, if $c$ denotes the length of the hypotenuse and $a$ and $b$ denote the lengths of the other two sides, we have
$$a^2 + b^2 = c^2$$ :::
These boxes are included in the document as fenced blocks, whose syntax is as follows:
title='Pythagorean theorem'} For a right triangle, if $c$ denotes the length of the hypotenuse and $a$ and $b$ denote the lengths of the other two sides, we have $$a^2 + b^2 = c^3$$ :::
The text block is delimited by ::: instead of the backquotes of code chunks.
The header of the block contains its name, prefixed by #.
The type of block follows, here: .greybox.
Arguments data-latex and title contain the title of the box in the PDF and HTML outputs, so a referenced text caption is useful to avoid repeating it.
Enter it in a paragraph starting with (ref:pythbox) followed by a space.
Then, call the text with the code (ref:pythbox).
This technique is identical to that used for elaborate figure captions.
Note the particular syntax of the title in the PDF output.
Grey text boxes (.greybox) are provided by the memoir template.
Advanced users can define other colored boxes, say a yellow box, following the next steps:
- Obtain the HTML code of the color, for instance with a color picker^824.
ffff66is suitable for yellow. - In
latex/preamble.tex, define the color by adding the following line below the definition of the grey color:
\definecolor{yellow}{HTML}{FFFF66}
- Also define the text box environment by duplicating the
greyboxitem and replacinggreywithyellowthree times:
\newmdenv[
style=boxstyle,
backgroundcolor=yellow,
frametitlebackgroundcolor=yellow,
]{yellowbox}
- In
style.css, duplicate all lines that define "Grey text box", including the starting and ending comment lines. Replace.greyboxwith.yellowboxeverywhere, "Grey" with "Yellow" in the comments and change thebackground-colorwith#ffff66. - In the text, use the same syntax as above but declare the class of the fenced block as
.yellowboxinstead of.greybox.
Documentation
User documentation
- The book bookdown: Authoring Books and Technical Documents with R Markdown by Yihui Xie, the author of bookdown and knitr. All the necessary details for writing (writing equations, cross-references, etc.) are given.
- The R Markdown cheat sheet for the syntax.
Documentation for developers
- LaTeX file format customization.
- The Pandoc manual for possible options in the YAML header.
Try the memoiR package in your browser
Any scripts or data that you put into this service are public.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.