# Authoring

## The `Knit` button

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

``` yaml
---
output:
  litedown::html_format: null
  litedown::latex_format: null
knit: litedown:::knit
---
```

## Live preview

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 (@sec:the-buttons), or call
`litedown::fuse()` (@chp:fuse) or `mark()` (@chp:mark) on the file.

### Live reload

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.

### The file listing

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
([⏵](){.larger}) 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.

::: callout-caution
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).
:::

### The buttons

```{css, echo=FALSE}
.larger { font-size: 1.5em; }
```

There is a button group at the top right of the preview page.

-   The `render` button (with the lightning or voltage icon, [↯](){.larger}): 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.

-   The `edit` buttons (with a pencil icon, [✎](){.larger}): Clicking on this
    button will open a plain-text file in your default editor.

-   The `back`/`forward` buttons (with arrow icons, [←](){.larger} and
    [→](){.larger}): 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, [⟳](){.larger}): 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, [⎙](){.larger}): 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.

## Visual editor

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.
