Release 8/11: decide on and publish the pkgdown docs site #49

New Issue

2026-08-08T18:44:53-04:00

jared commented

2026-08-08 18:44:53 -04:00

Depends on #47 (so the site's url: and the r-universe page agree).

_pkgdown.yml now indexes all 14 exports and builds clean. Publish it.

cog-api already solved this: it publishes a branded docs site to pages.civilytics.org/cog-api/ via a pages branch. See cog-api/docs/publishing-pages.md and scripts/publish_docs.R in crdc-arrests for the established pattern.

Decision

_pkgdown.yml currently sets url: https://civilytics.r-universe.dev/uscogdata. r-universe renders its own package docs, so a separate pkgdown site is optional, not required — the choice is whether you want a branded site at pages.civilytics.org/uscogdata/ alongside it.

If yes, update url: to the pages URL and reuse the cog-api publish pattern. If no, close this — r-universe covers it, and one less thing to keep alive.

Done when

Decided; if publishing, the site is live and url: matches

Depends on #47 (so the site's `url:` and the r-universe page agree). `_pkgdown.yml` now indexes all 14 exports and builds clean. Publish it. `cog-api` already solved this: it publishes a branded docs site to `pages.civilytics.org/cog-api/` via a `pages` branch. See `cog-api/docs/publishing-pages.md` and `scripts/publish_docs.R` in `crdc-arrests` for the established pattern. ## Decision `_pkgdown.yml` currently sets `url: https://civilytics.r-universe.dev/uscogdata`. r-universe renders its own package docs, so a separate pkgdown site is **optional**, not required — the choice is whether you want a branded site at `pages.civilytics.org/uscogdata/` alongside it. If yes, update `url:` to the pages URL and reuse the cog-api publish pattern. If no, close this — r-universe covers it, and one less thing to keep alive. ## Done when - [ ] Decided; if publishing, the site is live and `url:` matches

jared commented

2026-08-10 19:54:46 -04:00

Decided: no separate pkgdown site. r-universe covers it.

This issue framed the pkgdown site as optional, and the decision is not to publish one.

r-universe renders package documentation from the tag automatically. v0.4.0 is
tagged and mirrored, so once the registry is live the reference docs, vignettes and README
are all served at civilytics.r-universe.dev/uscogdata with no publish step of our own.
_pkgdown.yml already sets url: there, so nothing needs to change.

What a second site would cost. The cog-api pattern (orphan pages branch plus the
per-repo Git Pages Push webhook) works, but it is a publish step on every release, a
second URL to keep in sync with url:, and another thing that can silently go stale — the
webhook half of that pattern is easy to forget, and a pages branch without it serves
404s. cog-api has a branded site because it is a client-facing product with a landing page
and worked examples. A package reader is not that.

What we give up: branding, and a URL we control end to end. If uscogdata ever gets
long-form guides that outgrow vignettes, this is worth revisiting — at which point
url: changes and the cog-api pattern is there to copy.

_pkgdown.yml stays maintained and pkgdown::build_site() stays in the release checklist,
so the site remains one command away rather than needing reconstruction.

## Decided: no separate pkgdown site. r-universe covers it. This issue framed the pkgdown site as optional, and the decision is not to publish one. **r-universe renders package documentation from the tag automatically.** `v0.4.0` is tagged and mirrored, so once the registry is live the reference docs, vignettes and README are all served at `civilytics.r-universe.dev/uscogdata` with no publish step of our own. `_pkgdown.yml` already sets `url:` there, so nothing needs to change. **What a second site would cost.** The cog-api pattern (orphan `pages` branch plus the per-repo Git Pages Push webhook) works, but it is a publish step on every release, a second URL to keep in sync with `url:`, and another thing that can silently go stale — the webhook half of that pattern is easy to forget, and a `pages` branch without it serves 404s. cog-api has a branded site because it is a client-facing product with a landing page and worked examples. A package reader is not that. **What we give up:** branding, and a URL we control end to end. If uscogdata ever gets long-form guides that outgrow vignettes, this is worth revisiting — at which point `url:` changes and the cog-api pattern is there to copy. `_pkgdown.yml` stays maintained and `pkgdown::build_site()` stays in the release checklist, so the site remains one command away rather than needing reconstruction.

jared closed this issue

2026-08-10 19:54:46 -04:00

jared referenced this issue

2026-08-11 09:42:34 -04:00

Release 7/11: tag v0.4.0 and register with r-universe #47

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Civilytics/uscogdata#49