Overstorey

Quarto documentation site for plant: user guides, theory, and a version-pinned notebook. The API reference stays on the package's pkgdown site; this repo is the narrative layer.

The plant model family

Overstorey is the documentation repository in a three-repo family, with work coordinated on a shared project board ("Plant model development"):

Repository	Role
plant	Core C++/R model: size- and trait-structured demography, the SCM solver, and the physiological strategies (FF16, TF24, …).
regnans	Evolutionary community assembly on top of plant — invasion fitness, demographic equilibria, and selection gradients.
overstorey	The narrative documentation / field guide site — user guides, theory, worked reproductions (this repo).

Issues from all three repositories feed into the project board, which is the single place to see what is planned, in progress, or done across the family.

Why this exists

The vignette set had outgrown its format. This splits docs into:

• Guides — task-oriented walkthroughs (migrated from vignettes)
• Theory — the maths, consolidated from papers
• Adaptively (the notebook) — dated posts, each pinned to the plant version it was built against
• Reference — unchanged, links out to pkgdown

Reproducibility model

• execute: freeze: auto — a .qmd re-runs only when it changes. Commit _freeze/.
• renv.lock pins packages project-wide. CI restores it before rendering.
• Each notebook post declares its plant state in front matter:
  • master / released: plant-version: "2.1.0" → badge plant 2.1.0
  • develop / unreleased: plant-ref: "develop" + plant-sha: "a1b2c3d…" → badge ● plant @develop a1b2c3d (dashed, bark-toned, so it reads as a moving target pinned to a commit)
• Expensive posts can pin their own environment with a post-local renv.lock.dev (see posts/2026-06-10-hydraulics-benchmark/).
• Badges + footers are rendered from R/version-badge.R.

Cross-linking with pkgdown

The package's API reference stays on its pkgdown site. pkgdown-crosslink.yml holds the keys to merge into plant's own _pkgdown.yml so the two sites point at each other and share the canopy palette/fonts. This site's navbar "Reference" link already targets the pkgdown reference index.

Reproducing an old develop post

1. git -C plant checkout <plant-sha> (from the post's front matter)
2. renv::restore(lockfile = "posts/<slug>/renv.lock.dev")
3. delete that post's entry under _freeze/, then quarto render

Local build

quarto preview          # live reload
quarto render           # full build to _site/

Previewing a branch that isn't merged/published

CI publishes from master using the committed _freeze/, so it never needs a plant build. On a feature branch the same holds for any page you haven't touched — freeze: auto re-executes a page only when its own source changes. So the situation splits:

• Pages you didn't edit — quarto preview / quarto render renders them straight from the committed freeze; no plant required.
• Pages you edited that run R (a library(plant) setup chunk, inline helpers like plant_version_badge(), …) — their freeze is now stale, so Quarto tries to re-execute them and fails if plant isn't installed.

Just want to eyeball prose/layout, no plant build? Temporarily force Quarto to use the committed freeze for every page:

sed -i '' 's/  freeze: auto/  freeze: true/' _quarto.yml   # macOS; drop the '' on Linux
quarto render          # or: quarto preview — no plant needed
git checkout _quarto.yml                                    # revert; never commit this flip

This renders your new prose against the last-frozen computed output — accurate for markdown-only edits, but for edited code chunks you'll see new code with stale output (fine for a visual check, not a validation).

Don't reach for quarto render --no-execute: it disables the engine but still evaluates inline `r …` expressions and errors on them instead of falling back to the freeze.

Before the branch can merge/publish, the changed R pages must be re-executed for real and their freeze committed:

renv::restore()        # install plant at the pinned commit (compiles C++)

quarto render theory/<edited-page>.qmd   # regenerates that page's _freeze/
git add _freeze/ && git commit

The pr-checks freeze-consistency check gates the PR until the committed _freeze/ matches source.

First-time setup

install.packages("renv")
renv::init()            # snapshot current env -> renv.lock
renv::snapshot()        # after adding packages

Then commit renv.lock. For the badge helper: install.packages(c("htmltools","digest","here")).

Reporting issues

Documentation requests, corrections and feedback are welcome via the GitHub issue tracker. New issues are automatically added to the project board with status Backlog.

To keep the board sortable, please:

1. Apply one type label — the three repositories share the same set: bug (something is broken), task (a discrete piece of work — the default for docs), or epic (a larger capability spanning several tasks).

2. Prefix the title with a theme tag in square brackets. Most work here is [documentation]; use another existing theme where it fits, or [other]:

   [documentation] · [TF24 hydraulics] · [TF24 allometry] · [TF24 nsc] · [acclimation] · [simplify interface] · [evol assembly] · [Env drivers] · [speed] · [patch variations] · [other]

Plant family

overstorey is part of the plant family of packages in the traitecoevo org, built around the plant forest model. Docs hub: https://traitecoevo.github.io/overstorey/.

Contributing: please skim the family issue guide before filing — issues across the family are triaged on board #5, and cross-package context lives in plant-meta.