diff --git a/R/lago_report.R b/R/lago_report.R
index 11d98c8..ee2f0a9 100644
--- a/R/lago_report.R
+++ b/R/lago_report.R
@@ -29,7 +29,10 @@
 #' @return The path to the rendered HTML file, invisibly.
 #'
 #' @examples
-#' \donttest{
+#' # lago_report() renders an HTML file with rmarkdown, so it is wrapped in
+#' # \dontrun: it writes to disk and invokes pandoc, and running a document
+#' # render inside an in-process documentation build (e.g. pkgdown) can deadlock.
+#' \dontrun{
 #' result <- lago_optimization(
 #'   data = BB_data,
 #'   outcome_name = "pp3_oxytocin_mother",
diff --git a/man/lago_report.Rd b/man/lago_report.Rd
index aefe013..0392019 100644
--- a/man/lago_report.Rd
+++ b/man/lago_report.Rd
@@ -48,7 +48,10 @@ Rendering requires the \pkg{rmarkdown} and \pkg{knitr} packages (listed under
 Suggests). If they are not installed, an informative error is raised.
 }
 \examples{
-\donttest{
+# lago_report() renders an HTML file with rmarkdown, so it is wrapped in
+# \dontrun: it writes to disk and invokes pandoc, and running a document
+# render inside an in-process documentation build (e.g. pkgdown) can deadlock.
+\dontrun{
 result <- lago_optimization(
   data = BB_data,
   outcome_name = "pp3_oxytocin_mother",