# Publishing resources strategy (Quarto `resources:`)

Config: [`slide/course-xaringan.qmd`](../course-xaringan.qmd) YAML `resources:`.

Goal: **linked Xaringan HTML renders correctly** on `_site/`, without publishing author tooling (Rmd, build/cache R, knit hooks).

## Design (allowlist inside `scripts/`)

```mermaid
flowchart LR
  A["slide-xaringan/**"] --> B["!scripts/**"]
  B --> C["+ scripts/chapterNN/chunk-sources/**"]
  C --> D["_site mirror"]
```

1. Include the slide tree (HTML, `libs/`, `js/`, `*_files/`, …).
2. Exclude all of `scripts/` (build, cache, chapter `*.R` modules, `shared/`).
3. **Re-include** student supplement scripts under each chapter’s `chunk-sources/` and pre-rendered **`draws/chNN/out/*.svg`** (Drawings Lab via `build-drawings.R`).

This matches slide content: the same paths used in `file=` and in “R script download” footnotes.

| Publish | Do not publish |
|---------|----------------|
| `*.html` linked from the course index | `**/*.Rmd` |
| `libs/`, `js/mathjax-config.js` | `Rscript/` |
| `*_files/figure-html/` (Ch.18–20 plots) | `scripts/**` except allowlisted `chunk-sources/` |
| `scripts/chapter17/chunk-sources/*.R` | `scripts/chapter17/data/`, `build-cache.R`, `mroz-*.R`, … |
| `scripts/chapter17/mermaid/*.svg` | `scripts/chapter17/mermaid/*.mmd`, `build-mermaid.R` |
| `scripts/chapter17/diagram/*.svg` | `scripts/chapter17/diagram/*.R`, `build-diagram.R` |
| `draws/chNN/out/*.svg` | `draws/_shared/**`, `draws/**/tikz/**`, `draws/**/*.qmd`, `build-drawings.R` |

**Do not** use `!slide-xaringan/draws/**` then re-include `draws/*/out/*.svg` — Quarto treats the whole tree as excluded. Exclude Drawings Lab **sources** only; `ch17/out/*.svg` is listed explicitly in `course-xaringan.qmd`.
| `mycss/`, `pic/` (via `../` from HTML) | `**/*_cache/`, `**/*.RData`, `**/*.rds` |
| `slide-format/pdf/**` | `code/` (see `supplements-code.qmd`) |

**Order matters:** list `slide-xaringan/scripts/**/chunk-sources/**` after chapter-specific `!…/*.R` excludes.

**Gitignore:** do not use a repo-wide `scripts/**` rule — it prevents Quarto from copying `slide/slide-xaringan/scripts/`. Use `/scripts/**` for repo-root only (see root `.gitignore`).

## Slide ↔ site path alignment (Ch.17)

In `SEM-slide-eng-part0-IV-v3b.Rmd` (and v3a if needed):

````markdown
```{r, file='scripts/chapter17/chunk-sources/systemfit-m.R', echo=TRUE, eval=FALSE}
```

.footnote[
R script download: [`systemfit-m.R`](scripts/chapter17/chunk-sources/systemfit-m.R)
]
````

- `file=` and footnote use the **same** path → no duplicate copies, no `ch17-scripts/` mirror required.
- `copy_ch17_chunk_sources()` is **optional** (local-only duplicate); not needed for Quarto publish when using this strategy.

## Runtime dependencies (do not drop)

| Asset | Referenced from HTML as |
|-------|-------------------------|
| Remark / DT / panelset | `libs/...` |
| MathJax config | `js/mathjax-config.js` |
| Theme | `../mycss/...` → resource `mycss/**` |
| Figures & pics | `../pic/...` or `*_files/figure-html/` |

**Never** add `!slide-xaringan/**/*_files/**` — identification / SEM chapters need PNGs under `*_files/`.

## Other resource channels

| Path | How it is published |
|------|---------------------|
| `slide-xaringan/code/**` | **Excluded** here; [`supplements-code.qmd`](../supplements-code.qmd) has its own `resources: - slide-xaringan/code/**` |
| Orphan `*_files/` from removed drafts | Delete locally; only keep `*_files/` for decks still published |

## Adding a new chapter

When Ch.18 (or others) gets `chunk-sources/`:

```yaml
  - slide-xaringan/scripts/chapter18/chunk-sources/**
```

Keep footnotes as `scripts/chapter18/chunk-sources/foo.R`.

## Pre-publish checklist

```bash
# Refresh slides (also checks HTML + supplement link paths in v3b)
Rscript slide/slide-xaringan/scripts/chapter17/verify.R

# Build site (from repo root)
quarto render

# Spot-check _site/slide/slide-xaringan/
#   - SEM-slide-eng-part0-IV-v3b.html: layout, DT, images
#   - open scripts/chapter17/chunk-sources/systemfit-m.R (download link)
```

Optional: `Rscript slide/slide-xaringan/scripts/chapter17/check-site-resources.R`

## What we intentionally do not publish

- Knit hooks: `Rscript/wrap-display-math.R`, etc. (already in HTML output).
- Build pipeline: `build-cache.R`, `load-cache.R`, `verify.R`, `inf-mr-sync-check.R`.
- Cache blobs: `scripts/chapter17/data/ch17-cache.RData`.

Students get **supplement** `.R` files only—the same scripts already echoed on slides.

See [WORKFLOW.md](WORKFLOW.md) for authoring; [scripts/README.md](scripts/README.md) for chapter layout.