Skip to contents

Renders any folder — anywhere inside a larger git project — as a small standalone Quarto site in an isolated temp directory, leaving only a `_site/` artifact inside that folder. The generated site is marked with a small OFCE quick-publish banner for context. The slug (unique identifier) is computed from the folder's relative path within its repo and persisted in `_site/.adhoc-meta.json`.

Usage

render_flash(
  path = ".",
  index = NULL,
  slug = NULL,
  progress = TRUE,
  preview = TRUE,
  as_job = FALSE
)

Arguments

path

`[character(1)]`
Folder to render (relative or absolute). Defaults to `"."`.

index

`[character(1)]`
Filename (relative to `path`) of the file to treat as the home page (e.g., `"slides.qmd"`, `"notes.md"`). Must be a `.qmd` or `.md` file directly in `path`. If `NULL` (default), resolved via [adhoc_resolve_index()]: `index.qmd`/`index.md` if present, otherwise the most recently modified `.qmd`/`.md` candidate (an informational message names the file picked when more than one candidate exists). Only this single document is rendered — see Details.

slug

`[character(1)]`
Override the auto-computed slug (unique identifier). If `NULL` (default), computed via [adhoc_slug()] from the folder's relative path *and* the resolved `index` document's filename (without extension) – so two documents rendered separately out of the same folder get distinct slugs. Persisted in `_site/.adhoc-meta.json` for [deploy_flash()].

progress

`[logical(1)]`
If `TRUE` (default), progress is reported to the console.

preview

`[logical(1)]`
If `TRUE` (default), launches a live preview server via [servr::httw()] on the rendered site **when `as_job = FALSE`** only (ignored when `as_job = TRUE` — use [preview_flash()] afterwards instead).

as_job

`[logical(1)]`
If `TRUE` (default), and RStudio is available (checked via `rstudioapi::isAvailable()`), runs the render pipeline as a background job in RStudio's Background Jobs pane. All output (including errors) streams live to the Jobs pane console; when done, a summary appears in the global environment as `adhoc_last_render` (a list with `ok`, `url`, and optionally `error`). If `FALSE` or RStudio is unavailable, runs synchronously in the current session. See Details for integration patterns.

Value

Invisibly returns `NULL` when synchronous (`as_job = FALSE`) or RStudio unavailable. When `as_job = TRUE` with RStudio available, returns immediately and populates `adhoc_last_render` in the global environment when the job finishes.

Details

## Render pipeline

1. Resolves the enclosing git repository root from `path`. 2. Computes a deterministic `slug` (if not overridden). 3. Creates a scratch temp directory and copies `path`'s contents into it (excluding `_site/`, `.quarto/`, `_freeze/`, `.git*`). 4. Collects any `_extensions/` directories from `path` or its ancestors (up to the repo root) and includes them in the temp copy so extension shortcodes resolve correctly. 5. Writes a minimal `_quarto.yml` in the temp copy, restricted to `index` via `project.render` — so only that one document is built, regardless of how many other `.qmd`/`.md` files got copied alongside it. Any `_quarto.yml` already present in `path` is deliberately ignored (not merged): a flash render targets exactly one document, not a pre-existing multi-page project — use [render_site()]/[render_wp()] for that instead. If `index`'s own YAML frontmatter doesn't declare a `format`, `format: ofce-html` is added to this temp `_quarto.yml` only (never written back to the source file); if it does declare one, it's left as the document's own frontmatter dictates. 6. Checks for output-file collisions between the formats declared in `index` (only when there are 2+): each format's *resolved* output file is queried from `quarto inspect` and, if two formats write the same file – which would otherwise crash quarto's project step with a cryptic `NotFound ... rename` error – the render aborts early with an actionable message. If the query itself fails (exceptional), a frontmatter-only heuristic issues a non-blocking warning instead. 7. Renders the folder via `quarto::quarto_render()` in the temp directory. 8. Locates the HTML output for `index` and copies it to `_site/index.html` (preserving the original filename too). 9. Post-processes all `*.html` files to inject a small OFCE quick-publish banner right after the opening `<body...>` tag. 10. Cleans `.DS_Store` files, then copies the temp `_site/` into `<path>/_site/` (replacing if present). Writes metadata (slug, index, timestamp) to `_site/.adhoc-meta.json`. 11. If `preview = TRUE` and `as_job = FALSE`, launches [preview_flash()].

## Self-contained folders

The folder must be reasonably self-contained. Relative paths that climb outside it (e.g., `../shared-bib.bib`, `../../www/logo.png`) won't resolve in the temp copy, since only the folder itself (plus discovered `_extensions/`) is copied over. If `quarto_render()` fails on a missing file, check whether any includes are pointing outside the folder.

For R code (not Quarto includes/relative Markdown paths – see below), use [safe_here()] instead of [here::here()] in documents that might get rendered this way: it resolves paths against the *real* project root on disk (recorded before the copy is made), including for files that live outside the copied folder, rather than against the tempdir (which has no root marker of its own, and never contains those outside files anyway). It's a drop-in replacement – outside of a `render_flash()` temp copy it behaves identically to [here::here()].

## `.gitignore` housekeeping

We recommend adding `_site/` to the folder's `.gitignore` if not already present, so it isn't accidentally committed: “` echo "_site/" >> <path>/.gitignore “`

See also

[deploy_flash()], [publish_flash()], [preview_flash()], [render_prev()], [safe_here()]