fgczQuartoTemplate

One shared FGCZ look-and-feel for Quarto reports (theme + header + defaults), reusable across ezRun, prolfqua, prolfquapp, …. Reports can opt in to a top-right toolbar β€” πŸ” Find any figure or table in a graphical table of contents, or πŸ“₯ Download the plots, the .qmd source and a standalone copy of the page as a ZIP.

πŸ‘‰ See the documentation site β€” including a live example report with the real layout, tabsets, figures, and the Find / Download toolbar.

There are two ways to use it. Pick one.

Way 1 β€” Quarto extension (plain quarto render, no R)

Best when you render with the quarto CLI.

Step 1. In your project, once:

quarto add fgcz/fgczQuartoTemplate

This creates _extensions/fgczQuartoTemplate/ in the project. Without that extension directory, format: fgczQuartoTemplate-html will fail because Quarto cannot resolve the custom format.

Step 2. In your report’s YAML header:

---
title: "My report"
format: fgczQuartoTemplate-html
---

Step 3. Render:

quarto render my_report.qmd

Done. βœ…

Optional β€” πŸ” Find / πŸ“₯ Download / </> View source toolbar (off by default). Switch it on and select its buttons in the report header:

format:
  fgczQuartoTemplate-html:
    include-after-body: _extensions/fgczQuartoTemplate/fgcz-plot-finder.html
fgcz-buttons: [search, download, source]

Use fgcz-buttons: search (or any subset, e.g. [search, download]) to pick individual buttons. Omit fgcz-buttons to show all three when the toolbar is included. Unknown names stop the render instead of silently hiding controls. The View source button opens Quarto’s own view-source overlay and only appears when the report was rendered with code-tools: true (a template default already set in _metadata.yml).

Bonus β€” β€œShow code” per plot/table. Any figure/table chunk with #| label: fig-xxx / #| label: tbl-xxx and a matching fig-cap:/tbl-cap: automatically gets a small </> badge β€” on the figure itself and in the Find panel β€” that jumps to and highlights that chunk in View Source. No wiring needed beyond the label; unlabelled chunks show nothing extra.

Optional β€” tab colour and layout switches (all off by default). Three independent switches in the report header:

fgcz-colour: true      # per-nesting-level tab palette (deep blue β†’ indigo)
fgcz-number: true      # hierarchical tab numbers: 1, 1.1, 1.1.1 …
fgcz-full-width: true  # fill the screen instead of the centred body cap

fgcz-colour replaces the uniform grey folder tabs with one hue per nesting level, so depth reads as colour. fgcz-number prefixes every tab label with its position, counting across sibling tabsets at the same depth; with the toolbar on, the numbers show up in the Find panel’s breadcrumbs too. fgcz-full-width drops the centred body cap so content fills the screen on large displays (like the old ezRun html_document); it is unsupported with .column-margin / .column-screen.

Way 2 β€” R helper (stage files, then render)

Best when you render from R (e.g. inside a package). No format: line, no quarto add.

Step 1. Install:

remotes::install_github("fgcz/fgczQuartoTemplate")

Step 2. Your report’s YAML header β€” just this, nothing FGCZ-specific:

---
title: "My report"
---

Step 3. Render with the one-call helper:

fgczQuartoTemplate::fgcz_render("my_report.qmd")                 # no toolbar
fgczQuartoTemplate::fgcz_render("my_report.qmd", buttons = TRUE) # πŸ” Find / πŸ“₯ Download / </> View source
fgczQuartoTemplate::fgcz_render("my_report.qmd", buttons = "search") # πŸ” Find only
fgczQuartoTemplate::fgcz_render("my_report.qmd", colour = TRUE, number = TRUE) # coloured + numbered tabs
fgczQuartoTemplate::fgcz_render("my_report.qmd", full_width = TRUE) # content fills the screen

Done. βœ… (fgcz_render copies _metadata.yml, fgcz.scss, fgcz_header_quarto.html, and fgcz-plot-finder.html next to the .qmd, then calls quarto::quarto_render(). The toolbar is staged either way but only wired in when enabled. TRUE and FALSE remain supported; button names allow finer selection.)

If you want to separate these two steps, copy the assets first and render yourself:

input <- "my_report.qmd"
fgczQuartoTemplate::fgcz_copy_assets(input)
quarto::quarto_render(input)

fgcz_copy_assets() accepts either the .qmd path above, or an existing directory. These two calls are equivalent:

fgczQuartoTemplate::fgcz_copy_assets(input)
fgczQuartoTemplate::fgcz_copy_assets(dirname(normalizePath(input)))

Which one?

Way 1 β€” Extension Way 2 β€” R helper
Install quarto add … (once per project) install_github (once)
YAML format: fgczQuartoTemplate-html nothing
Render quarto render fgczQuartoTemplate::fgcz_render()
Use it when CLI / non-R pipelines rendering from R

Both produce the same report. They can coexist in one repo.

R helper cheatsheet (Way 2)

fgcz_render("report.qmd")               # stage assets + render (the usual one)
fgcz_render("report.qmd", buttons = TRUE) # ...plus the πŸ” Find / πŸ“₯ Download / </> View source toolbar
fgcz_render("report.qmd", buttons = "download") # ...or just πŸ“₯ Download
fgcz_render("report.qmd", colour = TRUE)  # per-level tab colours
fgcz_render("report.qmd", number = TRUE)  # tab numbers 1, 1.1, 1.1.1 …
fgcz_render("report.qmd", full_width = TRUE) # fill the screen (drops margin/screen columns)
fgcz_render("report.qmd", fig_dpi = 150, fig_retina = 1) # smaller self-contained HTML
fgcz_copy_assets("report.qmd")          # stage assets next to that file
fgcz_copy_assets("dir")                 # or stage assets into an existing dir
fgcz_use_template("dir", "report.qmd")  # start a new report from the template
fgcz_quarto_dir()                       # where the installed assets live
fgcz_qmd_source_link()                  # <a> link to this report's .qmd, for a Report provenance table

Why two mechanisms exist (30-second version)

Quarto can’t reach into an installed R package to fetch styling β€” the files must sit next to the .qmd at render time. Two clean ways to get them there:

  • Extension: quarto add drops them into _extensions/; you opt in with format:.
  • _metadata.yml: a file with that exact name is auto-applied to every .qmd in its directory (no format: line); the R helper stages it for you.

For maintainers

  • inst/quarto/ is the only place you hand-edit. Everything else is generated from it by Rscript data-raw/sync_assets.R (or make sync):
    • fgcz.scss, fgcz_header_quarto.html, fgcz-plot-finder.html, fgcz-buttons.lua β€” byte-copied into _extensions/ and vignettes/_extensions/.
    • _extensions/fgczQuartoTemplate/_extension.yml (nested, Way 1) β€” built from inst/quarto/_metadata.yml (flat, Way 2); edit the format options in _metadata.yml only. version is stamped from DESCRIPTION.
    • vignettes/example-report.qmd β€” built from inst/quarto/template.qmd (same body, vignette header swapped in); edit the report in template.qmd.
  • Install the hook once per clone: make hooks (or git config core.hooksPath .githooks). It runs the sync and re-stages the generated files on every commit, so editing inst/quarto/ is enough. CI (.github/workflows/altdoc.yml) re-runs the sync and fails on any drift as a backstop.
  • The live example report is the vignettes/example-report.qmd vignette; the documentation site (built with altdoc β€” make site) renders it through Quarto with its tabsets intact.

License

GPL (>= 3), matching ezRun.