Edit this chapter on GitHub
The litedown package is still new and experimental. The documentation is very incomplete. Besides, litedown was designed for minimalists with a limited scope. Average users should perhaps consider using rmarkdown or Quarto instead.
You may say I’m a dreamer
But I’m not the only one
I hope someday you’ll join us
And the world will live as one—John Lennon, Imagine
Imagine there’s no PDF. It’s easy if you try. No Word below us. Above us, only HTML.
I do not mean PDF and Word are bad. I only lament the time that human beings spend on various document formats, given how much a static web page can do.
Having worked on the development of R Markdown for nearly 12 years, I have to confess that I have become a little perplexed about my work, although I clearly remember the exciting moments. For example:
The moment when I added syntax highlighting to R code in .Rnw
documents.
Beautiful!
The moment when I managed to generate a base R plot and a ggplot in the same
code chunk and place them side by side in LaTeX. Magic! Not to mention that
ggplot does not require an explicit print()
call in a code chunk—you
probably do not even know what that means now.
The moment when I saw the impossible-to-read diagram that shows all possible conversions among numerous document formats on the Pandoc homepage. Incredible!
The moment when I discovered DZSlides in Pandoc. Wow! So PowerPoint and LaTeX beamer were not the only choices for slides.
The moment when some rstudio::conf attendees started applauding after I told them that the PowerPoint support had been added to the development version of rmarkdown when one person asked about it.
The moment when I came across remark.js. And tufte.css. And GitBook. And Hugo. And distill.pub. And htmlwidgets, reticulate, and so on.
…
I think the work was largely meaningful. The only problem is I do not see an end. The list of exciting things to do goes on and on.
“At forty, I had no more doubts.” Confucius said. Apparently, I’m not Confucius. On the contrary, as I’m turning forty, I’m having more doubts. I have been reflecting on the things that have kept me busy.
If I were to summarize the 700+ episodes of Naruto in one sentence, I would use the question that Gaara (the Fifth Kazekage) asked Onoki (the Third Tsuchikage):
When did you all forsake yourselves?
In my opinion, this question was the most critical turning point in the 700+ episodes, reminding the 79-year-old Onoki and the rest of people of their original dreams. The shinobi world existed to put an end to wars, but it turned out to bring even more and larger-scale wars.
When did we forsake simplicity? We create software to simplify things, but software often ends up in feature wars.
Markdown was originally invented for simplicity. That is, to make it easier to write HTML. I used to take out my wallet and tell people that if they are unable to learn the basics of Markdown in 5 minutes, I’d award them 20 dollars. I also used to say “In HTML I Trust”, which sounds like a joke, but I really love HTML and web technologies. Again, I do not mean other document formats are bad at all. It is just that I feel HTML has the greatest potential, and I hope to take full advantage of its power.1
In other words, I do not expect that “the (software) world will live as one”. I just want to make the HTML world a little bit better.
The litedown package is an attempt to reimagine R Markdown with one primary goal—do HTML, and do it well, with the minimalism principle. Before LaTeX fans walk away in disappointment, let me quickly clarify that LaTeX output is also supported, but please do not expect anything fancy before you learn to customize LaTeX templates. Most other output formats are not supported. No Word, RTF, PowerPoint, or EPUB.
R Markdown is rendered via litedown::fuse()
, which is similar to
rmarkdown::render()
and knitr::knit()
. Markdown is rendered via
litedown::mark()
, which uses commonmark instead of Pandoc.
The commonmark package follows the GFM (GitHub Flavored Markdown) spec, which can be seen as a subset of Pandoc’s Markdown. Therefore the litedown package can be viewed as a small subset of the current R Markdown ecosystem (the latter is based on Pandoc). It aims at simplicity, lightweight, and speed, at the cost of giving up some advanced features. This package is intended for minimalists. Most users may prefer using tools based on Pandoc instead, such as rmarkdown or Quarto, which offer richer features.
Is litedown really simple? From the developer’s perspective, yes, it is, largely due to the limited scope of the package. From the user’s perspective, some features are definitely not that simple. However, the point is that the core is simple and small, and you can enable or disable most features. What’s more, you can implement features by yourself if you know CSS/JS.
Almost everything in litedown was written from scratch. The package is very lightweight. Currently, it has two dependencies, commonmark and xfun. It does not depend on knitr or Pandoc.
It is a deliberate design choice to keep this package lightweight, to make it
relatively easy to use and simple to maintain. The functions mark()
and
fuse()
can be viewed as significantly trimmed-down versions of Pandoc and
knitr, respectively.
It is absolutely not the goal for litedown to become a substitute of tools based on knitr and Pandoc, such as rmarkdown and Quarto. If you are not sure if you should choose litedown or rmarkdown/Quarto, you may want to choose the latter (especially Quarto). Some litedown features may be ported into knitr in the future.
To get started, run litedown::roam()
and it will launch a file browser to let
you preview everything that can be rendered to HTML, such as .md
, .Rmd
, and
.R
files.
The rendering takes place in memory, which means it will not render .html
files on your disk, unless you request so. The page will be automatically
updated as you edit and save a file. This update-on-save feature can be turned
off, and then you can manually refresh the page to re-render the file whenever
you want.
You can open any file in your editor or the default system application by clicking a button in the browser. You can also render a file or a project in a new R session by clicking a button in the browser.
The R Markdown parser stores the precise line and column numbers of code
elements. The location information is used in various places. For example, when
an error occurs, you will get a message that tells you the precise location in
the source. In editors that support ANSI links (such as the RStudio IDE), you
can even click on the message to go to a specific line/column in the source
document, so you can quickly and easily know where the error occurred exactly.
When previewing .Rmd
documents with roam()
, you will see line numbers on the
left side of code blocks. Clicking on these numbers will bring you to the lines
in the source.
Due to the fact that the parser is based on commonmark (instead of solely on regular expressions like knitr’s parser), it can precisely recognize code chunks and inline code, which means code within other verbatim code blocks or comments will be untouched. For example:
````md
Below is not a code chunk but verbatim content
inside a fenced code block (with four backticks).
```{r}
1 + 1
```
Inline code expressions like `{r} 1+1` are not
parsed, either.
````
<!--
Feel free to comment out anything, such as a code chunk:
```{r}
1 + 1
```
-->
By default, litedown produces bare minimal HTML output, but many features can be enabled by adding CSS/JS assets (see 4). You can freely choose whatever versions that work for you to avoid potential future breakage when the assets are upgraded. The assets are not bundled in the litedown package, but hosted on CDN, so updating litedown will not update your assets.
The CSS and JS code for commonly used features do not depend on any frameworks such as Bootstrap or jQuery. They are simply vanilla code written from scratch. No generator was used (such as SCSS). The code is often relatively short, so you could just fork the code, modify it, publish your own version, and use it if you are not satisfied with the original version.
Chunk options are managed by an environment, i.e., litedown::reactor()
. Using
an environment (as compared to a list like knitr’s opts_chunk
) means you
can access the up-to-date chunk options anywhere, because environments in R are
mutable. I cannot explain how awkward knitr’s opts_current
has been. It is
basically a lie—chunk options that you get from opts_current
are not
necessarily “current”.
A document does not have to be compiled in the linear order. With the chunk
option order
, you can specify code chunks and inline code expressions to be
executed in an arbitrary order. For example, if you have an abstract in the
beginning of a document, and the abstract needs to use a number calculated at
the end of the document, you can let the abstract be compiled in the end,
although it appears earlier in the document.
I guess some users may want to kill me upon knowing this feature, and some may send me flowers (although I’m not sure if they want to thank me or prepare the flowers for my funeral). For those who want to kill me, please note that this feature does not mean litedown is as awful as Jupyter notebooks. It means you can specify a fixed order to execute code in the document. The order does not have to be from beginning to end, but it is deterministic. In other words, it does not mean you run code chunks in an arbitrary or random order that can detriment reproducibility.
If you want to figure out which code chunks are time-consuming, simply set the
chunk option litedown::reactor(time = TRUE)
in the beginning, and put
litedown::timing_data()
in the last code chunk. It will tell you detailed
information. In the roam()
preview, the data will also contain links to
specific lines of code chunks, so you click to jump to a specific code chunk.
Rectangular objects such as data frames (including tibbles) and matrices are printed as tables by default, and the number of rows is limited to 10 by default to avoid generating huge tables by accident.
File paths (such as image paths) have been a mess in knitr. My deepest apologies for that. I have worked much harder in litedown in this regard.
Functions such as mark()
, fuse()
, and fuse_book()
can operate in memory
without writing to disk. By default, if you pass a file input, you get a file
output; if you pass text input, you get text output.
You can feel more confident with using the chunk option cache = TRUE
in
litedown than in knitr. The new cache system is more robust and
intelligent.
Unlike bookdown and Quarto, litedown::fuse_book()
renders multiple input
files to a single output file. Yes, your whole precious book is in a single
(HTML or PDF) file. Grab and go.
The assumption of single-file output for books has made several things a lot
easier. For example, if you want to search within the book, just press
Ctrl + F
or Command + F
in your browser as you usually do on any other web
page. You do not need a client-side search library. It is also quicker to jump
between chapters because they are on the same page. If you want to print the
HTML version of the book to PDF, just press Ctrl + P
or Command + P
.
I know you have a concern: wouldn’t the single HTML file be too heavy for the browser? The answer is: you should be fine if you do not have too many images. If you do, do not base64 encode them (which is the default), and you can also lazy-load images to make the book load faster.
An R script has the same status as an R Markdown document. You can write
Markdown in #'
comments, and chunk options in #|
comments (both are
optional). These are the only two rules to remember. Compared to
knitr::spin()
, the rules are much simpler. Besides, R scripts are also
carefully parsed into “code chunks”, so their line numbers work as well as R
Markdown’s line numbers.
Any application that you can create with R Markdown can be created with R scripts, such as books and websites.
The HTML output generated from litedown is very clean. For example, code
blocks in HTML output contain plain code, instead of full of <span>
tags with
random attributes. Clean HTML output means the output file size is smaller, and
more importantly, it is easier to inspect the differences between two versions
of output (e.g., in Git). Every time when you update the source document, you
can know more clearly what has changed in the output, which can help you avoid
unexpected changes before publishing the output.
Output formats besides HTML and LaTeX are unlikely to be supported.2 If other output formats are desired, you may use Pandoc to do the conversion.
For tables, only pipe tables are supported. Other table formats are not recognized.
At the moment, litedown mainly supports R as the computing language. Other languages might be added in the future, but please keep your expectation low, because the support is unlikely to be as good as R.
HTML widgets are not supported yet, but may be reimagined in the future with some minimal support.
Edit this chapter on GitHub
R Markdown documents need to be knitted to Markdown before being rendered to a
target output format. The function litedown::fuse()
plays a role similar to
knitr::knit()
. It “fuses” program code with narratives, i.e., it executes all
code in the source document and interweaves results with narratives in the
output document. Similar to knitr, litedown supports code chunks and
inline code.
A code chunk consists of the language name, chunk options (in the chunk header or pipe comments), and the code:
```{lang}
#| chunk options
code
```
Currently, a subset of knitr chunk options are
supported, which can be accessed in litedown::reactor()
. To get an option
value, use reactor("NAME")
, where NAME
is the option name (e.g.,
fig.width
). To set an option globally, use reactor(NAME = VALUE)
.
Alternatively, you can manipulate the value returned by reactor()
directly,
which is essentially an environment:
opts = litedown::reactor()
opts$fig.width # get an option
opts$echo = FALSE # set an option
Code chunks inside other code blocks are not parsed or evaluated, which provides a way to write verbatim code chunks, e.g.,
````markdown
Some verbatim content.
```{r}
1 + 1
```
````
Similarly, code in comments will not be recognized, either, e.g.,
<!--
Do not run this chunk:
```{r}
1 + 1
```
or the inline code `{r} pi`.
-->
If N + 1
pairs of curly braces are used in the opening fence, the chunk fences
(with N
pairs of curly braces) and chunk options will be shown in the output,
which can be useful for telling readers the full source of a chunk, e.g.,
```{{r}}
#| echo = TRUE, eval = FALSE
1 + 1
```
The syntax for inline code expressions is `{lang} code`
, where lang
is
the language name, e.g., r
. Spaces are allowed after the opening backtick and
before the closing backtick. If the code
happens to contain N
backticks, you
will need to use at least N + 1
backticks outside, e.g.,
``{r} paste("`", rnorm(1), "`")``
. An inline code expression inside
another piece of inline code is not parsed or evaluated, which provides a way to
write verbatim inline code expressions, e.g., `` `{lang} code` ``
.
Comma-separated chunk options can also be provided to inline code expressions
after the language name, e.g., `{r, eval=FALSE} code`
.
For knitr users, please note that the syntax `r code`
is not supported
by default. You have to wrap the language name r
in curly braces. As a
temporary workaround, you may set options(litedown.enable.knitr_inline = TRUE)
in your .Rprofile
to make litedown recognize `r code`
, but we
recommend that you convert the document via litedown:::convert_knitr()
instead
if you decide to stay with litedown in the long run.
If the inline expression returns a single number, the number will be formatted.
To bypass the formatting, wrap the inline expression in I()
. We denote the
number by \(x\) for now.
First, \(x\) will be rounded to \(n\) significant digits, where \(n\) is
controlled by the global R option litedown.inline.signif
and its default
value is 3
. To change the default, set
options(litedown.inline.signif = N)
anywhere before the inline code is
executed, where N
is the desired number of significant digits.
Then \(x\) will be formatted using the scientific notation \(\pm m\times 10^n\)
if \(|x| \geq 10^p\) or \(|x| \leq 10^{-p}\), where \(p\) is controlled by the
global option litedown.inline.power
, which defaults to 6
. If you want to
avoid the scientific notation, you can set this option to Inf
.
When a number is formatted in the scientific notation, you need to wrap it
in an inline LaTeX math expression. For example, $`{r} 1234567`$
will
be rendered to \(1.23 \times 10^{6}\).
Besides R Markdown, you can also pass an R script to fuse()
. You can write
Markdown content in #'
comments, and group lines of code into chunks by #|
comments, e.g.,
#' ---
#' title: An R script
#' output:
#' litedown::latex_format: null
#' ---
#'
#' A _paragraph_.
#| eval=FALSE
1:10
1 + 1
#| fig.width=10, dev='pdf'
plot(cars)
Both #'
and #|
comments are optional.
Currently, the main computing language supported by litedown is R. You can check all supported languages via:
names(litedown::engines())
#> [1] "css" "mermaid" "js" "md" "r"
You can get a language engine definition via litedown::engines('LANG')
, where
LANG
is the language name, e.g.,
litedown::engines('md')
You can also set a new language engine via:
litedown::engines(LANG = function(x, inline = FALSE, ...) {
})
The function’s argument x
is an element in the list returned by
litedown::crack()
.
The md
engine will output Markdown text both verbatim and as-is, which can be
useful for showing Markdown examples, e.g.,
```{md}
You can see both the _source_ and _output_ of
this `md` chunk.
```
You can also use `{md} the engine **inline**`.
You can insert CSS/JS to the output via the css
/js
engines, e.g.,
```{css}
a {
color: red;
}
```
```{js}
document.body.classList.add('dark');
```
The mermaid
engine can be used to draw diagrams with
mermaid.js, e.g.,
```{mermaid, flow-abcd, echo=FALSE, fig.cap='A flowchart.'}
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
The JS library mermaid.js has to be loaded for the diagrams to be rendered. By
default, the latest version of mermaid.js will be added to the js
variable
(3.3.2.2) in the YAML metadata automatically. If you prefer using a
specific version, you can add it manually to the YAML metadata, e.g.,
---
title: "A mermaid diagram"
output:
litedown::html_format:
meta:
js: ["@npm/[email protected]/dist/mermaid.min.js"]
---
```{mermaid}
```
Major differences between knitr and litedown include:
knitr | litedown |
---|---|
Supports multiple graphical devices for a chunk. | Only supports one device for a chunk (but there are multiple choices for this device). |
Depending on certain chunk options, figure output could be both Markdown (![]() ) and raw HTML (<img> ) / LaTeX (\includegraphics{} ). |
Always use Markdown syntax for figures. |
The document parser is based on regular expressions and not robust. Code chunks and inline expressions are not aware of their contexts (e.g., code blocks or comments). | The parser is based on commonmark, which is more robust and makes it straightforward to write verbatim code (in a parent code block) or comment out code (in <!-- --> comments). |
Supports a large number of chunk options and language engines. | Supports a limited number of chunk options and engines. |
Inline code does not support options or languages other than R. | Inline code supports options and other languages. |
All code is executed in the linear order. | Code chunks and inline code can be executed in a custom non-linear order defined by the chunk option order (higher values indicate higher priority). |
Supports chunk hooks and output hooks. | No hooks at the moment. |
The package is more than 12 years old and quite mature. | The package is new and still experimental. |
If you feel any indispensable features are missing in litedown, please feel free to suggest them in Github issues. However, please remember that the goal of litedown is not to fully re-implement rmarkdown, knitr or Pandoc. Some features may never be re-implemented, especially when the implementation is not simple enough.
Edit this chapter on GitHub
For the full list of supported document elements, please read the GFM spec. Below is a quick summary:
Headings start with a number of #
’s, e.g., ## level-two heading
.
Inline elements: **strong**
, _emphasis_
, ~~strikethrough~~
,
[text](link)
, and ![alt](image/path)
.3
Inline code is written in a pair of backticks, e.g., `code`
. Code
blocks can be indented, or fenced by ```
.
List items start with -
, +
, or *
, e.g., - item
. A task list item is
a regular list item with [ ]
or [x]
in the beginning, e.g.,
- [ ] item
.
Block quotes start with >
.
Tables are created with |
as the column separator (i.e., Pandoc’s pipe
table, which can be generated by knitr::kable(x, "pipe")
or
xfun::md_table()
).
In addition to GFM features, the litedown package also supports the following features.
Raw LaTeX and HTML blocks can be written as fenced code blocks with language
names =latex
(or =tex
) and =html
, e.g.,
```{=tex}
This only appears in \LaTeX{} output.
```
Raw LaTeX blocks will only appear in LaTeX output, and will be ignored in other output formats. Similarly, raw HTML blocks will only appear in HTML output. One exception is raw LaTeX blocks that are LaTeX math environments, which also work for HTML output (see the next section).
You can write both $inline$
and $$display$$
LaTeX math, e.g.,
\(\sin^{2}(\theta)+\cos^{2}(\theta) = 1\).
$$\bar{X} = \frac{1}{n} \sum_{i=1}^n X_i$$
$$|x| = \begin{cases} x &\text{if } x \geq 0 \\ -x &\text{if } x < 0 \end{cases}$$
For expressions in pairs of single or double dollar signs to be recognized as
LaTeX math, there must be no spaces after the opening dollar sign, or before the
closing dollar sign. The math expression should either start from the very
beginning of a line, or have a space or (
before the opening dollar sign.
For a pair of single dollar signs, they must be on the same line in the text, and the closing dollar sign should not be followed by a number (to avoid detecting math mistakenly from text like “a $5 bill and a $10 bill”). The inner math expression should not be wrapped in backticks.
For $$ $$
expressions, they can span over multiple lines, in which case
the closing $$
must have at least one non-space character before it, and
no spaces after it.
Valid examples:
$x + y$
($x + y$)
$x + y$
text $x + y$ text
$$x + y$$
$$x + y$$
text $$x + y$$ text
$$x +
y$$
Invalid examples:
$ x + y$ <- space after the opening `$`
text$x + y$ <- lack of space before the opening `$`
text $x + y$10 text <- number after closing `$`
$x +
y$ <- multi-line `$ $` expressions
$`x + y`$ <- expression wrapped in backticks
$$x +
y
$$
^- lack of non-space character before closing `$$`
LaTeX math environments are also supported, e.g., below are an align
environment and an equation
environment:
\begin{align}
a^{2}+b^{2} & = c^{2}\\
\sin^{2}(\theta)+\cos^{2}(\theta) & = 1
\label{eq:pyth-identity}
\end{align}
\begin{equation}
\begin{split}
(a+b)^2 &=(a+b)(a+b)\\
&=a^2+2ab+b^2
\end{split}
\end{equation}
\begin{align} a^{2}+b^{2} & = c^{2}\\ \sin^{2}(\theta)+\cos^{2}(\theta) & = 1 \label{eq:pyth-identity} \end{align}
\begin{equation} \begin{split} (a+b)^2 &=(a+b)(a+b)\\ &=a^2+2ab+b^2 \end{split} \end{equation}
These math environments can be written as either nake LaTeX code or raw LaTeX
blocks (```{=latex}
), but we recommend that you use raw LaTeX blocks
because they are more robust. LaTeX math environments work for both LaTeX and
HTML output.
For HTML output, it is up to the JavaScript library (MathJax or KaTeX) whether a math environment can be rendered (3.1.5).
Write superscripts in ^text^
and subscripts in ~text~
(same syntax as
Pandoc’s Markdown), e.g., 210 and H2O. Currently only alphanumeric
characters, *
, (
, and )
are allowed in the scripts. For example, a^b c^
will not be recognized as a superscript (because the space is not allowed). Note
that GFM supports striking out text via ~text~
, but this feature has been
disabled and replaced by the feature of subscripts in litedown. To strike
out text, you must use a pair of double tildes.
Insert footnotes via [^n]
, where n
is a footnote number (a unique
identifier). The footnote content should be defined in a separate block starting
with [^n]:
. For example:
Insert a footnote here.[^1]
[^1]: This is the footnote.
The support is limited for LaTeX output at the moment,4 and there are two caveats if the document is intended to be converted to LaTeX:
The footnote content must be a single paragraph.
Only numbers5 are supported as identifiers, and other types of identifiers are not recognized.
The two limitations do not apply to HTML output, e.g., you can write arbitrary elements in footnotes and not necessarily one paragraph.
Attributes on images, links, fenced code blocks, and section headings can be
written in {}
. ID and class are two common attributes. An ID can be written
after the #
character, and a class can be written after .
. Attributes are
typically written in the form name="value"
, and separated by spaces (in fact,
you can also write IDs and classes explicitly like other attributes, e.g.,
id="foo" class="bar"
). Certain attributes do not require values, and you can
provide the attribute name only, e.g., disabled
or contenteditable
, although
it is harmless to write disabled="true"
.
Only lowercase letters (a-z), digits (0-9), hyphens (-
), and colons (:
) are
allowed in ID and class strings. For example, sec:intro
and fig-cars
are
valid IDs, but sec_intro
and tab cars
are not.
For example, ![text](path){.foo #bar width="50%"}
will generate an <img>
tag
with attributes in HTML output:
<img src="path" alt="text" id="bar" class="foo" width="50%" />
and ## Heading {#baz}
will generate:
<h2 id="baz">Heading</h2>
Links of the form [text](url){...}
will generate:
<a href="url" ...></a>
When the url
is empty, <a>
will be converted to <span>
, e.g.,
[text](){.foo .bar}
will generate:
<span class="foo bar">text</span>
This provides a way to create <span>
elements, which is similar to bracketed
Span
s (i.e.,
[text]{...}
) in Pandoc’s Markdown.
For fenced code blocks, a special rule is that the first class name will be
treated as the language name for a block, and the class
attribute of the
result <code>
tag will have a language-
prefix. For example, the following
code block
```{.foo .bar #my-code style="color: red;"}
```
will generate the HTML output below:
<pre>
<code class="language-foo bar" id="my-code" style="color: red;">
</code>
</pre>
Most attributes in {}
are ignored for LaTeX output except for:
The width
attribute for images, e.g., ![text](path){width="50%"}
will be
converted to \includegraphics[width=.5\linewidth]{path}
.
The .unnumbered
attribute, which will make a heading unnumbered, e.g.,
# Hello {.unnumbered}
will be converted to \section*{Hello}
.
The .appendix
attribute on a heading, which will start the appendix, e.g.,
# Appendix {.appendix}
will be converted to \appendix
.
When a top-level heading has the attribute .appendix
, the rest of the document
will be treated as the appendix. If section numbering is enabled
(3.1.8), the appendix section headings will be numbered
differently.
Div
sA fenced Div
can be written in :::
fences. Note that the opening fence must
have at least one attribute, such as the class name. For example:
::: foo
This is a fenced Div.
:::
::: {.foo}
The syntax `::: foo` is equivalent to `::: {.foo}`.
:::
::: {.foo #bar style="color: red;"}
This div has more attributes.
It will be red in HTML output.
:::
A fenced Div
will be converted to <div>
with attributes in HTML output,
e.g.,
<div class="foo" id="bar" style="color: red;">
</div>
For LaTeX output, it can be converted to a LaTeX environment if both the class
name and an attribute data-latex
are present. For example,
::: {.tiny data-latex=""}
This is _tiny_ text.
:::
will be converted to:
\begin{tiny}
This is \emph{tiny} text.
\end{tiny}
The data-latex
attribute can be used to specify arguments to the environment
(which can be an empty string if the environment doesn’t need an argument). For
example,
::: {.minipage data-latex="{.5\linewidth}"}
will be converted to:
\begin{minipage}{.5\linewidth}
If a fenced Div
doesn’t have the data-latex
attribute, the fence will be
ignored, and its content will be written out normally without a surrounding
environment. If a fenced Div
has multiple class names (e.g., {.a .b .c}
),
only the first class name will be used as the LaTeX environment name. However,
all class names will be used if the output format is HTML (e.g.,
<div class="a b c">
).
To cross-reference an element, it must be numbered first. Then we can refer to it by its ID.
Section heading IDs can be either manually assigned or automatically generated
(3.1.1). Section numbers are automatically generated if the
number_sections
option is true (3.1.8).
Figures and tables are automatically numbered if their captions are provided
(via the chunk options fig.cap
/ tab.cap
), e.g.,
```{r}
#| nice-plot, fig.cap="A nice caption"
plot(cars)
```
To refer to an element in the text, use the syntax @ID
, where ID
is the ID
of the element to be referenced, which typically consists of a prefix (e.g.,
sec:
, fig:
, tab:
, or eq:
) and a label. For example:
Please see @fig:nice-plot for an overview of the `cars` data.
Hyphens (-
) are also allowed in place of colons in the ID prefix, e.g.,
@fig-nice-plot
.
LaTeX math environments such as align
and equation
are numbered by default.
To refer to an expression (e.g., an equation) in a math environment, a label
needs to be assigned to the expression first via \label{}
, and it must start
with the prefix eq:
or eq-
, e.g.,
```{=latex}
\begin{equation}
\sin^2(x) + \cos^2(x) = 1 \label{eq:pyth-identity}
\end{equation}
```
Then we can use either @eq:*
or @eqn:*
to cross-reference the equation,
e.g., @eqn:pyth-identity
. Under the hood, the prefix @eq
will be resolved to
\ref{}
, and @eqn
will be resolved to \eqref{}
. If you are not familiar
with LaTeX commands \ref{}
and \eqref{}
, the main difference is that
\eqref{}
will render the equation number in parentheses, e.g.,
\(\eqref{eq:pyth-identity}\), whereas \ref{}
will only generate the equation number,
e.g., \(\ref{eq:pyth-identity}\).
In HTML output, \eqref{}
will also add a label “Equation” before the number by
default. If you prefer writing the label manually and having control over the
parentheses, you can use @eq:
instead of @eqn:
, e.g., Eq. [@eq:*]
(using
the label “Eq.” and square brackets).
In addition to equation numbers, you can also specify a tag for an equation via
\tag{}
and refer to the equations by its tag, e.g.,
For a right-angled triangle, we are all familiar with @eqn:pyth-theorem.
\begin{equation}
a^2 + b^2 = c^2 \label{eq:pyth-theorem} \tag{PT}
\end{equation}
For a right-angled triangle, we are all familiar with \(\eqref{eq:pyth-theorem}\).
\begin{equation} a^2 + b^2 = c^2 \label{eq:pyth-theorem} \tag{PT} \end{equation}
You can cross-reference any other type of elements by adding empty anchors of
the form [](#@ID)
into them, e.g.,
::: {style="background: ghostwhite; padding: 1px 1em;"}
[](#@blk:example) This is a numbered block.
:::
We can cross-reference @blk:example.
1 This is a numbered block.
We can cross-reference 1.
For HTML output, we can style the numbers and references with CSS. Element
numbers are wrapped in <span class="ref-number-*"></span>
, and references are
wrapped in <span class="cross-ref-*"></span>
, where *
is the ID prefix
(e.g., fig
, tab
, and eqn
). For example, we can add the label “Block” to
the number and reference of the block above:
.ref-number-blk::before, .cross-ref-blk::before {
content: "Block ";
}
.ref-number-blk {
font-weight: bold;
font-style: italic;
}
.ref-number-blk::after {
content: ". "
}
This feature requires the R package rbibutils. Please make sure it is installed before using citations.
xfun::pkg_load2("rbibutils")
To insert citations, you have to first declare one or multiple bibliography databases in the YAML metadata, e.g.,
bibliography: ["papers.bib", "books.bib"]
Each .bib
file contains entries that start with keywords. For example,
R-base
is the keyword for the following entry:
@Manual{R-base,
title = {R: A Language and Environment for Statistical Computing},
author = {{R Core Team}},
organization = {R Foundation for Statistical Computing},
address = {Vienna, Austria},
year = {2024},
url = {https://www.R-project.org/},
}
Then you can use [@R-base]
or @R-base
to cite this item. The keywords must
consist of only alphanumeric characters (a-z
, A-Z
, 0-9
) and -
. You can
include multiple keywords in [ ]
separated by semicolons.
For HTML output, the citation uses the author-year style. The syntax
[@keyword]
generates the citation in parentheses (e.g., (Author, 2024)
), and
@keyword
only puts the year in parentheses (e.g., Author (2024)
).
For LaTeX output, the citation style depends on the LaTeX package, which you can
set via the citation_package
option of the output format in YAML metadata,
e.g.,
output:
litedown::latex_format:
citation_package: biblatex
The default is natbib
. The table below shows the LaTeX commands corresponding
to the Markdown citation syntax:
citation package | [@key-1; @key-2] |
@key |
---|---|---|
none | \cite{key-1, key-2} |
\cite{key} |
natbib | \citep{key-1, key-2} |
\citet{key} |
biblatex | \parencite{key-1, key-2} |
\cite{key} |
Note that litedown actually generates \citep
and \citet
regardless of
the citation package, but will redefine them to \cite
or \parencite
according to the citation package. For example, it will insert
\let\citep\parencite
in the LaTeX preamble when citation_package
is
biblatex
.
“Smart” HTML entities can be represented by ASCII characters, e.g., you can
write fractions in the form n/m
. Below are some example entities:
1/2 |
1/3 |
2/3 |
7/8 |
1/7 |
1/9 |
1/10 |
(c) |
(r) |
(tm) |
---|---|---|---|---|---|---|---|---|---|
½ | ⅓ | ⅔ | ⅞ | ⅐ | ⅑ | ⅒ | © | ® | ™ |
As mentioned earlier, a lot of features in Pandoc’s Markdown are not supported in the litedown package. Any feature that you find missing in previous sections is likely to be unavailable. In addition, a lot of R Markdown and Quarto (both are based on Pandoc) features are not supported, either. Some HTML features have been implemented via JavaScript and CSS.
Pandoc can convert Markdown to many output formats, such as Word, PowerPoint, LaTeX beamer, and EPUB. The litedown package is unlikely to support output formats beyond HTML and LaTeX.
Edit this chapter on GitHub
The main function to convert Markdown to other formats is litedown::mark()
.
You can either call litedown::mark()
to render a Markdown document
programmatically, or click the Knit
button in RStudio to render a (Markdown or
R Markdown) document interactively. The latter requires you to specify the
output format in the output
field in YAML metadata (3.3), e.g.,
---
output:
litedown::html_format:
options:
js_math:
package: "katex"
version: "0.16.4"
number_sections: true
embed_resources: ["local", "https"]
meta:
css: "custom.css"
---
The options
argument of mark()
can be used to enable/disable/set options to
control Markdown rendering. This argument can take either a list, e.g.,
list(toc = TRUE, smart = FALSE)
, or a character vector, e.g.,
c("+toc", "-smart")
, or equivalently, +toc-smart
, where +
means to enable
an option, and -
means to disable an option. The options can also be set in
YAML metadata in 3.3 (recommended). Available options are listed
below.
auto_identifiers
Add automatic IDs to headings, e.g.,
# Hello world!
## Introduction
will be converted to
<h1 id="chp:hello-world">Hello world!</h1>
<h2 id="sec:introduction">Introduction</h2>
The prefix chp:
(chapter) will be added to the automatic IDs of level-one
headings, and sec:
(section) will be added for other levels of headings.
You can override the automatic ID by providing an ID manually via the ID attribute, e.g.,
# Hello world! {#hello}
An automatic ID is generated by substituting non-alphanumeric characters in the
heading text with hyphens. If the result is empty, the ID will be section
. If
any ID is duplicated, a numeric suffix will be added to the ID, e.g.,
example_1
and example_2
.
embed_cleanup
Whether to clean up plot files after they have been embedded in HTML output (see 3.1.3).
embed_resources
Embed resources (images, CSS, and JS) in the HTML output using their base64-encoded data (images) or raw content (CSS/JS). Possible values are:
null
or false
: Do not embed any resources.
"local"
or true
: Embed local image/CSS/JS files.
"https"
: Embed web resources (links that start with https://
).
"all"
: An alias to the union of "local"
and "https"
.
The default is "local"
, i.e., local resources are embedded, whereas https
resources are not. This means the output document may not work offline. If you
have to view the output offline, you need to use the option value "https"
(or
"all"
) and render the document at least once before you go offline.
js_highlight
Specify the JavaScript library to syntax highlight code blocks. Possible values
are highlight
(highlight.js) and prism
(Prism.js). The default is prism
. This option can also
take a list of the form list(package, version, style, languages)
, which
specifies the package name (highlight
or prism
), version, CSS style/theme
name, and names of languages to be highlighted.
You can find information about Prism.js from its CDN at
https://cdn.jsdelivr.net/npm/prismjs/. Available styles are under the
themes/
directory (e.g., prism-dark
), and languages are under the
components/
directory (e.g., prism-c
). You can omit the prefix prism-
,
e.g.,
js_highlight:
package: prism
style: dark
languages: [r, latex, yaml]
The CDN of highlight.js is at
https://cdn.jsdelivr.net/gh/highlightjs/cdn-release/build/. Themes are
under the styles/
directory (e.g., github
), and you can find demos of
themes at https://highlightjs.org/static/demo/. Supported language are
under the languages/
directory (e.g., latex
).
By default, languages are automatically detected and the required JS files are
automatically loaded. Normally you need to specify the languages
array only if
the automatic detection fails.
Technically this option is a shorthand for setting the metadata variables css
and js
in 3.3. If you want full control, you may disable this
option (set it to false
or null
) and use metadata variables directly, which
requires more familiarity with the JS libraries and the jsdelivr CDN.
js_math
Specify the JavaScript library for rendering math expressions in HTML output.
Possible values are "mathjax"
and "katex"
(the default). Like the
js_highlight
option, this option is also essentially a shorthand for setting
the metadata variables css
and js
.
For MathJax, the js
variable is
set to tex-mml-chtml.js
.
For KaTeX, the js
variable is set
to katex.min.js
and the css
variable is set to katex.min.css
. KaTeX’s
auto-render
extension (auto-render.min.js
) is also enabled by default,
so math expressions can be immediately rendered when the page is loaded.
If you want finer control, you can provide a list of the form
list(package, version, css, js)
. This will allow you to specify the package
name, version, and css/js files. For example, if you want to use MathJax’s
tex-chtml.js
instead, you may set:
js_math:
package: mathjax
version: 3
js: es5/tex-chtml.js
By default, MathJax version 3 is used. If you want to use the older v2, you may set:
js_math:
package: mathjax
version: 2
js: MathJax.js?config=TeX-AMS-MML_CHTML
Please visit the MathJax CDN to know which versions and JS files are available.
For KaTeX, the version is not specified by default, which means the latest
version from the CDN. Below is an example
of specifying the version 0.16.4 and using the mhchem
extension:
js_math:
package: katex
version: 0.16.4
js: [dist/katex.min.js, dist/contrib/mhchem.min.js]
Note that if you want the HTML output to be self-contained via the
embed_resources
option, KaTeX can be embedded and used offline, but MathJax
cannot be fully embedded due to its complexity. MathJax v3 can be partially
embedded and used offline, but currently only its fonts can be embedded, and
extensions cannot. If you must view HTML output offline, we recommend using
KaTeX, but please also note that KaTeX and MathJax do not fully cover each
other’s features.
keep_yaml
Whether to keep the YAML metadata in the output. When TRUE
, the original YAML
in the Markdown input (if exists) will be written to the output. Note that when
this option is enabled, templates (3.2) will be disabled and mark()
will only generate a document fragment. This option was introduced mainly for
Hugo websites to use litedown instead of Hugo’s Markdown engines to render
pages.
latex_math
Whether to identify LaTeX math expressions in pairs of single ($ $
) or double
dollar signs ($$ $$
), and transform them so that they could be correctly
rendered by MathJax (HTML output) or LaTeX.
number_sections
Whether to number section headings. To skip numbering a specific heading, add a
class attribute .unnumbered
(or use the shorthand -
) to it. For example:
## Preface {.unnumbered}
## About the author {-}
smartypants
Whether to translate certain ASCII strings into smart typographic characters
(see ?litedown::smartypants
).
superscript
Whether to translate strings between two carets into superscripts, e.g.,
text^foo^
to text<sup>foo</sup>
.
subscript
Whether to translate strings between two tildes into subscripts, e.g.,
text~foo~
to text<sub>foo</sub>
.
toc
Whether to generate a table of contents (TOC) from section headings. If a
heading has an id
attribute, the corresponding TOC item will be a link to this
heading. You can also set a sub-option:
depth
: The number of section levels to include in the TOC (3
by
default). Setting toc
to true
is equivalent to:
toc:
depth: 3
To exclude a certain heading from the TOC, assign a class name unlisted
to it.
For example:
## Acknowledgments {.unlisted}
top_level
The desired type of the top-level headings in LaTeX output. Possible values are
'chapter'
and 'part'
. For example, if top_level = 'chapter'
, # heading
will be rendered to \chapter{heading}
instead of the default
\section{heading}
.
Options not described above can be found on the help pages of commonmark,
e.g., the hardbreaks
option is for the hardbreaks
argument of
commonmark::markdown_*()
functions, and the table
option is for the table
extension in commonmark’s extensions.
litedown::markdown_options()
#> [1] "-hardbreaks" "-number_sections" "-smartypants"
#> [4] "-tagfilter" "-toc" "+auto_identifiers"
#> [7] "+autolink" "+cross_refs" "+embed_cleanup"
#> [10] "+embed_resources" "+js_highlight" "+js_math"
#> [13] "+latex_math" "+smart" "+strikethrough"
#> [16] "+subscript" "+superscript" "+table"
#> [19] "+tasklist"
# commonmark's arguments
opts = formals(commonmark::markdown_html)
opts = opts[setdiff(names(opts), c('text', 'extensions'))]
unlist(opts)
#> hardbreaks smart normalize sourcepos footnotes
#> FALSE FALSE FALSE FALSE FALSE
# commonmark's extensions
commonmark::list_extensions()
#> [1] "table" "strikethrough" "autolink" "tagfilter"
#> [5] "tasklist"
By default, mark()
generates a document fragment (i.e., the body) if the input
does not contain YAML metadata at the beginning. To generate a full document,
you need to specify YAML metadata. A full document is generated with a template.
Below is a simple HTML template example:
<html>
<head>
<title>$title$</title>
</head>
<body>
$body$
</body>
</html>
It contains two variables, $title$
and $body$
. All variables will be
substituted by metadata values, except for $body$
, which is from the body of
the input document (after conversion to a target output format).
The litedown has provided default templates for
HTML
and
LaTeX
output. To pass metadata to templates, use the meta
argument, e.g.,
litedown::mark(..., meta = list(title = "My Title"))
If you want to use a custom template file, you can set the path in the global
option litedown.FORMAT.template
(where FORMAT
is the output format name
(html
or latex
), e.g., in .Rprofile
:
options(litedown.html.template = 'path/to/my/template.html')
The global option will be applied to all documents to be converted by mark()
.
Alternatively, you can pass a template path to the template
argument of the
output format litedown::html_format
or litedown::latex_format
in an
individual document, e.g.,
---
output:
litedown::html_format:
template: "path/to/my/template.html"
---
The template path can also take a logical value: TRUE
means to use the default
template, and FALSE
means to generate only a fragment document without using
any template.
Alternatively, the meta
argument can read YAML metadata in the Markdown
document.
The following variables can be set in the top-level fields in YAML:
abstract
: The abstract.
author
: The document author(s).
date
: The date.
subtitle
: The document subtitle.
title
: The document title.
For example:
---
title: "My Title"
author: "[Frida Gomam](https://example.com)"
date: "2023-01-09"
---
The values are treated as Markdown text, and will be converted to the target
output format before being passed to the template. For the above example, the
variable $author$
will be <a href="https://example.com">Frida Gomam</a>
in
the HTML template.
For top-level variables, mark()
will also create the “underscore” versions for
templates, which contain HTML and LaTeX markups. For example, for the $title$
variable, $title_$
will also be available to the template. The following table
shows the values of the underscore variables, assuming the original value of a
variable is TEXT
:
Variables | HTML | LaTeX |
---|---|---|
$title_$ |
<div class="title"> <h1>TEXT</h1> </div> |
\title{TEXT} |
$subtitle_$ |
<div class="subtitle"> <h2>TEXT</h2> </div> |
\subtitle{TEXT} |
$author_$ |
<div class="author"> <h2>TEXT</h2> </div> |
\author{TEXT} |
$date_$ |
<div class="date"> <h3>TEXT</h3> </div> |
\date{TEXT} |
$abstract_$ |
<div class="abstract"> <p>TEXT</p> </div> |
\begin{abstract} TEXT \end{abstract} |
If an original variable is empty or missing, its underscore version will also be
empty. For the $author_$
variable, if the $author$
variable contains
multiple author names as an array, each name will be in a separate <h2>
in
HTML output, and all names will be concatenated by \and
in LaTeX output, e.g.,
for
author: ["Jane X", "John Y"]
in YAML, the HTML output will be:
<div class="author">
<h2>Jane X</h2>
<h2>John Y</h2>
</div>
and the LaTeX output will be:
\author{Jane X \and John Y}
If you design your own template, you are free to use either the original or the
underscore versions of these variables. For example, you could put the title in
an <h1>
without the <div>
wrapper via <h1 class="title">$title$</h1>
instead of using $title_$
.
When these top-level variables are also provided as meta
variables for an
output format, the latter will override the former, e.g.,
title: "Global Title"
output:
litedown::html_format:
meta:
title: "Title for HTML output"
litedown::latex_format:
meta:
title: "Title for LaTeX output"
Other variables need to be specified under
output -> litedown::*_format -> meta
, where *
can be html
or latex
,
e.g.,
---
title: "My Title"
output:
litedown::html_format:
meta:
css: "style.css"
js: "script.js"
litedown::latex_format:
meta:
documentclass: "book"
header_includes: "\\usepackage{microtype}"
---
The following metadata variables are supported for both HTML and LaTeX templates:
header-includes
, include-before
, include-after
: Either a vector of
(HTML/LaTeX) code or a code file to be included in the header, before the
body, or after the body of the output.The following variables are for HTML templates:
css
variableA vector of CSS files to be included in the output. The default value is
litedown:::pkg_file('resources', 'default.css')
.
If you want to use built-in CSS files in this package, you can only specify the
base name, e.g., default
means default.css
in this package.
You can also use web resources, e.g., https://example.org/style.css
. One
special case is jsdelivr resources: if a css
value
starts with @
, it will be recognized as a jsdelivr.com resource. if you are
not familiar with jsdelivr, you may read its documentation to understand the
following example URLs. The shorthand syntax is as follows (CDN
stands for
https://cdn.jsdelivr.net
):
@foo
(without a filename extension) will be converted to
CDN/npm/@xiee/utils/css/foo.min.css
, e.g., @default
means
CDN/npm/@xiee/utils/css/default.min.css
. If you prefer the .css
extension over .min.css
, you can use @default.css
.
@foo@version
(a filename followed by a version number) will be converted
to CDN/npm/@xiee/utils@version/css/foo.min.css
, e.g., @[email protected]
means CDN/npm/@xiee/[email protected]/css/article.min.css
.
@path/to/file
(i.e., a value that contains slashes) will be converted to
CDN/path/to/file
, e.g., @npm/@xiee/utils/js/center-img.js
will be
converted to CDN/npm/@xiee/utils/js/center-img.min.js
.
@path/to/file-1,file-2
(comma-separated values and later values do not
contain slashes) will be converted to
CDN/combine/path/to/file-1,path/to/file-2
(this can be useful to
combine
multiple resources and load all at once).
@path-1/to/file-1,path-2/to/file-2
(comma-separated values and later
values contain slashes) will be converted to
CDN/combine/path-1/to/file-1,path-2/to/file-2
.
This provides a way to reduce the output HTML file size by loading CSS from the
web instead of embedding inside HTML, at the cost of requiring Internet
connection when viewing the HTML file. If you need the external web resources to
work after you go offline, you can enable "https"
in the Markdown option
embed_resources
in advance to embed the resources.
js
variableA vector of JavaScript files to be included in the output. The syntax is the
same as the css
variable, e.g., snap
means snap.js
in this package,
@snap
means a “jsdelivr” resource, and you can use arbitrary paths or URLs to
other JS files.
body-class
variableA class name for the main body (the default value is body
).
The following variables are for LaTeX templates:
classoption
variableA string containing options for the document class.
documentclass
variableThe document class (by default, article
).
A variable name must consist of alphanumeric characters and hyphens only. You
could use underscores in variable names in the metadata, but please note that
underscores will be normalized to hyphens internally, e.g., header_includes
will be converted to header-includes
. This means if you use a custom template,
you must use hyphens instead of underscores as separators in variable names in
the template.
The above are variables supported in the default templates. If you use a custom
template, you can use arbitrary variable names following the naming convention
(except for body
, which is a reserved name and cannot be used in metadata),
and the values of variables in the metadata will be passed to your template.
Besides metadata variables, the aforementioned Markdown options
(3.1) can also be set in YAML under
output -> litedown::*_format -> options
, e.g.,
output:
litedown::html_format:
options:
toc: true
js_highlight:
package: highlight
theme: github
languages: [diff, latex]
See the help page ?litedown::html_format
for possible fields in addiction to
meta
and options
that can be specified under the format name, e.g.,
output:
litedown::latex_format:
latex_engine: xelatex
keep_md: true
template: custom-template.tex
Edit this chapter on GitHub
The litedown package aims at lightweight with a minimal number of features
at its core, but you can add more features by yourself. In this chapter, we
introduce some CSS/JS assets from the GitHub repository
https://github.com/yihui/misc.js. You can load arbitrary external JS and CSS
files via the js
and css
meta variables. There are numerous JS libraries and
CSS frameworks on the web that you can use, and you do not have to use the ones
mentioned in this chapter. You can also write CSS/JS by yourself to enhance your
HTML applications.
Remember that the CSS and JS are introduced under the output format
litedown::html_format
in YAML metadata, e.g.,
---
output:
litedown::html_format:
meta:
css: ["one.css", "two.css"]
js: ["three.js", "four.js"]
---
For the sake of brevity, we will omit the full YAML fields in examples
throughout this chapter but only use the css
and js
fields. A file name
foo.js
denotes the file under the js/
directory of the aforementioned
yihui/misc.js
repository. Similarly,
foo.css
is under the css/
directory.
All these CSS/JS resources can be used offline, and there are two ways to do it. One way is to clone the GitHub repo to your working directory, and use the files you need, e.g.,
js: ["repo/path/js/callout.js"]
Another way is to enable embedding resources:
output:
litedown::html_format:
meta:
js: ["@callout"]
options:
embed_resources: ["https"]
After you have embedded CSS/JS resources once when you have Internet access,
these resources will be cached locally and will not require an Internet
connection again. This solution works for any online resources, not limited to
the yihui/misc.js
repository.
With snap.css
and snap.js
, you can create lightweight HTML slides:
css: ["@default", "@snap"]
js: ["@snap"]
You can learn more in vignette('slides', package = 'litedown')
.
You can style an HTML page in an article format via the following CSS and JS:
css: ["@default", "@article"]
js: ["@sidenotes", "@appendix"]
The article.css
is mainly for styling the article frontmatter, body, and side
content.
The sidenotes.js
is required only if you want to place certain elements on
the left or right side, such as the table of contents (TOC), footnotes, and
sidenotes.
The appendix.js
is required only if you have an appendix in the article.
The web version of this book is also based on the article format, so you know what an article format looks like when you read the HTML version of the book.
The maximum width of the article body is 800px. For larger screens, this means there will be extra space in the left/right margin, where we can place auxiliary information, such as the TOC and footnotes. On smaller screens, the side content will be collapsed into the body.
The article frontmatter, body, and optionally the appendix are placed in separate boxes.
The default typeface is sans-serif, and you can customize it by supplying an
external CSS file (via the css
meta variable) or just embedding CSS in the
document body, e.g.,
```{css, echo=FALSE}
body {
font-family: Palatino, "Book Antiqua", Georgia, serif;
font-size: 1em;
}
```
The TOC and footnotes are automatically placed in the margin if space permits.
You can also write arbitrary content in the margin via a fenced Div
.
The TOC is sticky on the left side as you scroll down the article. If you do not like this behavior, you may cancel it via CSS:
#TOC {
top: unset;
}
Footnotes are moved to the right side. When you move your cursor over a footnote number in the body, the footnote will be moved next to your cursor. This can be convenient when you have multiple footnotes on a line, since you do not need to look for a specific footnote in the margin.
You can write anything in the margin by using a fenced Div
with the classes
.side
and .side-left
or .side-right
.
Notice
Here is a note on the left side. Anything permitted by law is permitted here. Math? No problem!
$$e^{i\theta}=\sin{\theta}+i\cos{\theta}$$
When you have this sidenote “hammer”, I’m sure you will hit a lot of nails into the margin, even if you do not have to.
::: {.side .side-left}
**Anything** on the left.
:::
::: {.side .side-right}
_Anything_ on the right.
:::
Inside the article body, you can write a few special elements.
When an element is wider than the article body, you can show it in its full
width by enclosing the element in a fenced Div
with the class .fullwidth
,
e.g.,
::: {.fullwidth}
![text](path/to/image)
:::
If you use R Markdown, you can generate a wide plot or table from an R code chunk, e.g.,
::: {.fullwidth}
```{r}
#| sunspots, echo=FALSE, fig.dim=c(14, 4),
#| fig.cap='Monthly mean relative sunspot numbers from 1749 to 1983.'
par(mar = c(4, 4, .1, .1), bg = 'lightyellow', fg = 'red', las = 1)
plot(sunspots, col = 'red')
grid()
```
:::
If you want to show code (echo = TRUE
) but do not want the code to be in the
full-width container, you can apply the .fullwidth
class to the plot only,
e.g.,
```{r}
#| sunspots, fig.dim=c(14, 4), fig.env='.fullwidth .figure .box',
#| fig.cap='Monthly mean relative sunspot numbers from 1749 to 1983.'
par(mar = c(4, 4, .1, .1), bg = 'lightyellow', fg = 'red', las = 1)
plot(sunspots, col = 'red')
grid()
```
Whenever you find that you are on the side of the majority, it is time to pause and reflect.
Sometimes you may want to add a quote but do not want it to take the full width
in the body. You may use a fenced Div
with the class .quote-left
or
.quote-right
.
Despite the class names, the content does not have to be a quote. If you do want
a quote, just use the blockquote syntax >
, e.g.,
::: {.quote-right}
> This is a boring quote.
>
> ---Someone
:::
You can embed elements on the left or right margin using a fenced Div
with the
class .embed-left
or .embed-right
. These elements will float to the left or
right and exceed the margin by about 200px, which can save some space in the
article body. You can use the extra space to explain the embedded element with
text.
We have embedded a table of the first 4 rows of the mtcars
data on the right
margin, which you can see if the browser window is wide enough.
You can load the script tabsets.js
and CSS tabsets.css
to create tabsets
from sections (see documentation
here).
css: ["@tabsets"]
js: ["@tabsets"]
Code folding is supported by fold-details.js
(see documentation
here).
js: ["@fold-details"]
A callout block is a fenced Div with the class name callout-*
. Callouts
require callout.css
and callout.js
:
css: ["@callout"]
js: ["@callout"]
For example:
::: callout-tip
This is a tip.
> You can write arbitrary content, such as a blockquote.
You can even _nest another callout_ into this one!
Is that cool?
:::
This is a tip.
You can write arbitrary content, such as a blockquote.
You can even nest another callout into this one!
Is that cool?
The stylesheet callout.css
supports styling tip
, note
, caution
,
warning
, important
, and example
callouts. For example:
Thank you for your notice! Your notice has been noted.
Be careful when testing for strict equality of floating point numbers.
seq(0, 1, .2) == c(0, .2, .4, .6, .8, 1)
#> [1] TRUE TRUE TRUE FALSE TRUE TRUE
Never try to out-stubborn a cat!
For the sake of reproducibility, please remember to render an R Markdown document in a new R session before publishing or submitting the output document.
::: {.callout-example data-legend="Demo"}
Change the title of this example to "Demo".
:::
Change the title of this example to “Demo”.
You do not have to use callout.css
but can define your own CSS rules, e.g.,
.callout-important {
background: red;
color: yellow;
}
Under the hood, callout.js
turns the fenced Div into a <fieldset>
for the
form:
<fieldset class="callout-*">
<legend>Title</legend>
Content.
</fieldset>
The content comes from the original fenced Div. The title comes from the class
name (converted to uppercase) by default. You can provide a custom title via the
data-legend
attribute of the Div, e.g.,
::: {.callout-tip data-legend="Information"}
:::
The icons before the callout titles can be defined via CSS, e.g., you can add
two exclamation marks before the title of important
callouts:
.callout-important legend::before {
content: "!! ";
}
The default icons defined in callout.css
are essentially UTF-8
characters. In theory,
there are hundreds of thousands of characters that you can choose from. Each
character is 1 to 4 bytes. For example, you can define a music
callout with
the music note symbol ♫ in the CSS:
.callout-music {
background: springgreen;
border-color: yellow;
}
.callout-music legend::before {
content: "♫ ";
}
Then you can insert a music
callout in your document:
::: callout-music
Please listen to this lovely song.
:::
Alternatively, if you are using callout.css
, you can also use CSS variables to
define the border color, background, and icon of a callout, e.g.,
.callout-music {
--callout-background: springgreen;
--callout-border: yellow;
--callout-icon: "♫ ";
}
You can use the script right-quote.js
to right-align a blockquote footer if it
starts with an em-dash (---
).
js: ["@right-quote"]
The CSS is necessary only if you want to hide the anchors by default and reveal them on hover.
css: ["@heading-anchor"]
js: ["@heading-anchor"]
The script key-button.js
identifies keys and the CSS styles them, which can be
useful for showing keyboard
shortcuts.
css: ["@key-buttons"]
js: ["@key-buttons"]
Of course, you can combine any number of JS scripts and CSS files if you want multiple features.
Edit this chapter on GitHub
Knit
buttonIf you use the RStudio IDE, the Knit
button can render R Markdown to a
litedown output format specified in YAML (e.g., litedown::html_format
or
litedown::latex_format
). Please also remember to add a top-level setting
knit: litedown:::knit
in YAML, otherwise RStudio will use knitr::knit()
instead of litedown::fuse()
to compile R Markdown.
---
output:
litedown::html_format: null
litedown::latex_format: null
knit: litedown:::knit
---
Unless it has become your muscle memory to click on the Knit
button in
RStudio, you may try to switch to litedown::roam()
to preview your HTML
output. Note that the preview takes place in memory only. Although you see an
HTML page rendered from a file in the preview, the page is not rendered to disk,
unless you click on the render button (5.2.3), or call
litedown::fuse()
(1) or mark()
(3) on the file.
By default, the preview will automatically refresh the content after you edit
and save a file. If you prefer building the document only when you want to, you
can turn off the live preview via litedown::roam(live = FALSE)
. In this case,
the document will be rebuilt only when you refresh the page by yourself.
After launching the preview via litedown::roam()
, a file listing will be
displayed, which shows the first few lines of *.R
, *.Rmd
, and *.md
files
in boxes, followed by the list of other files.
By clicking on plain-text files, you will see their full content. For binary files, they may be opened in your browser; if they cannot be opened, the browser may prompt to download the file.
Each file will have its size displayed after the filename, with a link attached to the file size. The link points to the raw file (the behavior of the link is up to the browser—the file may be opened or downloaded), and litedown will not process it at all.
The full path of the file or directory being previewed is displayed at the top left.
For .R
, .Rmd
, and .md
files, you can click on the “Run” button
(⏵) to render them to HTML in memory and preview the output. This
button is displayed at the top right of each file box on the listing page, and
at the top right of the preview page of an individual file.
Rendering .R
and .Rmd
files via the Run
button means the full R code in
them will be executed. If the R code involves intensive computing, it may not be
a good idea to run the whole file, unless you have taken measures to speed up
the computing (e.g., via caching).
There is a button group at the top right of the preview page.
The render
button (with the lightning or voltage icon, ↯): It
renders a document or project in a new R session and save the output file(s)
to disk, which is similar to what the Knit
button does in RStudio.
You can also use the keyboard shortcut Ctrl + K
(or Command + K
on
macOS).
The edit
buttons (with a pencil icon, ✎): Clicking on this
button will open a plain-text file in your default editor.
The back
/forward
buttons (with arrow icons, ← and
→): They are similar to the back/forward buttons on web browser
toolbars, and can be used to go back/forward through the browsing history.
You can also use the keyboard shortcuts Alt + Left
/ Alt + Right
.
The refresh
button (with the refresh icon, ⟳): It can be used
to refresh the page. If you are previewing an Rmd file, refreshing the page
will rebuild it.
You can also use the keyboard shortcut Ctrl + R
(or Command + R
on
macOS).
The printer
button (with a printer icon, ⎙): It brings up the
printer dialog, e.g., you can print the page to PDF.
Code blocks in the preview mode will have line numbers automatically added to their left. If you click on a line number, it will bring you to that line in the source document.
Note that the keyboard shortcuts require the page to be currently on focus before they can take effect. This is important when you are viewing a page inside RStudio or other IDEs, because the viewer may not gain focus automatically, and you will have to explicitly click on it.
Previewing .Rmd
and .R
files that generate plots will leave *__files/
directories (containing plot files) on disk by default. If you want to clean up
such directories when closing or navigating away from the preview page, you may
set the option
options(litedown.roam.cleanup = TRUE)
before you run litedown::roam()
or in your .Rprofile
. Note that it will not
clean up a *__files/
directory if it has existed before you preview a file.
This is to make sure roam()
will not delete existing files by accident. If you
are certain that a *__files/
directory can be safely deleted, you can always
delete it by hand. After that, roam()
will automatically clean it up when you
preview the file again.
Please also note that when caching is enabled (via the chunk option
cache = TRUE
) in the file being previewed, the *__files/
directory will not
be cleaned up, because when a code chunk is cached, it will not be re-evaluated
or re-generate plots next time (unless the cache is invalidated).
Since the Markdown syntax of litedown can be viewed as a subset of Pandoc’s Markdown, you can use RStudio’s visual Markdown editor to author documents. Please bear in mind that most common, but not all, Markdown features are supported.
Edit this chapter on GitHub
Books and websites are usually based on multiple input files under a directory.
For a directory to be recognized as a book or website project, it needs to
contain a configuration file named _litedown.yml
.
If you want to customize the output formats html_format
or latex_format
for
books or websites, you should do it in _litedown.yml
, e.g.,
output:
litedown::html_format:
options:
toc:
depth: 4
litedown::latex_format:
meta:
documentclass: "book"
The _litedown.yml
file should contain a top-level field named book
, which
currently supports these options:
book:
new_session: false
subdir: false
pattern: "[.]R?md$"
chapter_before: "Information before a chapter."
chapter_after: "This chapter was generated from `$input$`."
You can choose whether to render each input file in a new R session, whether to
search subdirectories for input files, the types of input files (e.g., you can
use .md
or .R
files if you want), and additional information to be included
before/after each chapter, in which you can use some variables such as
$input$
, which is the path of each input file.
R package developers can build the full package documentation as a book. A
series of helper functions have been provided in litedown to get various
information about the package, such as the package description (pkg_desc()
),
news (pkg_news()
), citation (pkg_citation()
), source code (pkg_code()
),
and all manual pages (pkg_manual()
). You can call these functions in code
chunks to print out the desired information. For example, you may put them in
the appendix (2.2.6):
# Appendix {.appendix}
# Package Metadata
```{r, echo=FALSE}
litedown::pkg_desc()
```
To cite the package:
```{r, echo=FALSE}
litedown::pkg_citation()
```
# News
```{r, echo=FALSE}
litedown::pkg_news(recent = 0) # show full news
```
# Manual pages
```{r, echo=FALSE}
litedown::pkg_manual()
```
# Source code
```{r, echo=FALSE}
litedown::pkg_code()
```
The _litedown.yml
file should contain a top-level field named site
, and you
are likely to customize the meta
variables css
, include_before
, and
include_after
for the html_format
, e.g.,
site:
rebuild: "outdated"
pattern: "[.]R?md$"
output:
litedown::html_format:
meta:
css: ["@default"]
include_before: "[Home](/) [About](/about.html)"
include_after: "© 2024 | [Edit]($input$)"
Basically, include_before
can take a file or text input that will be used as
the header of each web page, and include_after
will be the footer.
Edit this chapter on GitHub
The litedown package has also provided two internal output formats for
compatibility with rmarkdown: litedown:::html_document
and
litedown:::pdf_document
.6 The purpose is to make it a little
easier to switch from rmarkdown to litedown by mapping some
rmarkdown output format options to litedown.
For example, for an R Markdown document with the following output format:
output:
html_document:
toc: true
number_sections: true
anchor_sections: true
self_contained: false
You can switch to litedown simply by changing the output format name from
html_document
to litedown:::html_document
. Internally, the above output
format is transformed to:
output:
litedown::html_format:
options:
toc: true
number_sections: true
embed_resources: false
meta:
css: ["default", "@heading-anchor"]
js: ["@heading-anchor"]
Note that not all rmarkdown options are supported, and not even all
supported options have exactly the same effects in litedown. The supported
options include:
toc
, toc_depth
, number_sections
, anchor_sections
, code_folding
, self_contained
, math_method
, css
, and includes
.
Edit this chapter on GitHub
To build package vignettes with litedown, first add this to the package
DESCRIPTION
file:
VignetteBuilder: litedown
Then use the vignette engine litedown::vignette
in the YAML metadata of a
.Rmd
or .md
vignette file:
vignette: >
%\VignetteEngine{litedown::vignette}
%\VignetteIndexEntry{Your vignette title}
%\VignetteEncoding{UTF-8}
The output format of a vignette can be specified in the output
field of the
YAML metadata, e.g., litedown::html_format
(for HTML vignettes) or
litedown::latex_format
(for PDF vignettes). If no output format is specified,
the default is HTML.
The vignette file can be either .Rmd
or .md
. The former is processed by
litedown::fuse()
, and the latter is converted by litedown::mark()
. Please
avoid using the same base filename for two .Rmd
and .md
files, otherwise
their output files will overwrite each other.
Edit this chapter on GitHub
When https
resources needs to be embedded (via the embed_resources
option),
only these elements are considered:
<img src="..." />
<link rel="stylesheet" href="...">
<script src="..."></script>
Background images set in the attribute style="background-image: url(...)"
are
also considered. If an external CSS file contains url()
resources, these
resources will also be downloaded and embedded.
It’s quite simple to move an element into the margin using CSS. For example, the
.side-right
class in this article is roughly defined as:
.side-right {
width: 200px;
float: right;
margin-right: -200px
}
That basically means the width of the element is 200px and it floats to the
right. Now its right side will touch the right margin of its parent element (the
article body). What we need to do next is move it further to the right by 200px
(i.e., its width), which is done by the -200px
right margin. Remember, a
positive right margin in CSS moves an element to the left, and a negative right
margin moves it to the right.
At one night, as I was thinking about Pandoc Lua filters, an obvious fact suddenly came to my mind: suppose all I care about is HTML output, then the good old JavaScript can actually play a perfect role of Lua filters, because you can manipulate the DOM arbitrarily with JavaScript. ↩
In fact, xml,
man
, text
, and commonmark
output formats are
supported (thanks to the commonmark package), but perhaps they are not
very useful to average users. ↩
Please note that for links and images, their URLs should not
contain spaces. If
they do, the URLs must be enclosed in <>
, e.g.,
![alt](<some dir/a subdir/foo.png>).
↩
If you know C, I’ll truly appreciate it if you could help with the LaTeX implementation in GFM: https://github.com/github/cmark-gfm/issues/314 ↩
The specific number doesn’t matter, as long as it’s a unique
footnote number in the document. For example, the first footnote can be
[^100]
and the second can be [^64]
. Eventually they will appear as [1]
and [2]
. If you use the RStudio visual editor to edit Markdown documents,
the footnote numbers will be automatically generated and updated when new
footnotes are inserted before existing footnotes. ↩
The triple-colon :::
means these functions are not exported,
which is to avoid name conflicts between the two packages. ↩