grafana / grafana/interactive-tutorials
Adopt renderer:website conditions for website-only media blocks
- Dominant language
- HTML
- Stars
- 13
- Forks
- 8
- Avg merge
- 2d 4h
- Merged PRs (30d)
- 45
Description
## Summary
Test and adopt Pathfinder's existing **renderer conditions** so website-oriented media (videos, screenshots, etc.) can live in the same `content.json` as interactive steps, but only render on the website / Learning Hub — not in Pathfinder.
This replaces the earlier idea of a new `hide` flag ([grafana-pathfinder-app#1417](https://github.com/grafana/grafana-pathfinder-app/issues/1417)). The Pathfinder team confirmed the need is already met via conditions, e.g. `"conditions": ["renderer:website"]` on a **conditional** block wrapping the media.
Docs: [requirements-reference.md (renderer conditions)](https://github.com/grafana/grafana-pathfinder-app/blob/main/docs/developer/interactive-examples/requirements-reference.md) (see the renderer conditions section).
## Approach (from Pathfinder team)
1. Wrap website-only blocks (`video`, `image`, and similar conceptual/media blocks) in a `conditional` block.
2. Set conditions so they render on the website renderer only, e.g.:
```json
{
"type": "conditional",
"conditions": ["renderer:website"],
"blocks": [
{
"type": "video",
"src": "https://www.youtube.com/embed/BDJO-vC-gEw",
"provider": "youtube",
"title": "Verify metrics query successful",
"start": 349
}
]
}
```
3. Do **not** wrap interactive / guided / multistep action steps this way — those should stay visible in Pathfinder.
4. Note ergonomics: each media block needs a conditional wrapper today. If that feels heavy after real use, Pathfinder may later consider a per-block `condition` property (larger surface area). Capture feedback while testing.
## Work items
### 1. Spike / test the approach
- [ ] Pick 1–2 existing guides (or a milestone) that include video and/or image blocks
- [ ] Wrap those media blocks in `conditional` + `renderer:website`
- [ ] Verify in Pathfinder: media does **not** show; interactive steps still work
- [ ] Verify website / deploy preview / Learning Hub rendering: media **does** show
- [ ] Note any schema, Block Editor, or authoring friction (especially wrapping ergonomics)
### 2. Migrate published guides
- [ ] Inventory published packages with `video` / `image` (and other website-oriented media) in `content.json`
- [ ] Migrate those blocks to `conditional` + `renderer:website` where Pathfinder should suppress them
- [ ] Spot-check Pathfinder + website for a representative sample after migration
- [ ] Open PR(s); keep changes focused on media suppression unless a guide needs related cleanup
### 3. Update authoring skill / docs
- [ ] Document the pattern in the relevant skill(s) and/or authoring docs (e.g. create/update guide skills, `docs/json-guide-reference.md`, best practices)
- [ ] Make clear: website-only media → wrap in conditional with `renderer:website`; action steps stay unwrapped
- [ ] Add a short example authors can copy
## Acceptance criteria
- [ ] Spike confirms Pathfinder hides website-conditioned media and website still shows it
- [ ] Published guides that currently bloat Pathfinder with video/image are migrated (or explicitly skipped with rationale)
- [ ] Skills/docs instruct authors to use this pattern going forward
- [ ] Feedback on wrapper ergonomics captured (issue comment or follow-up) for Pathfinder if it feels painful
## References
- Pathfinder discussion / prior ask: [grafana-pathfinder-app#1417](https://github.com/grafana/grafana-pathfinder-app/issues/1417)
- Renderer conditions: [requirements-reference.md](https://github.com/grafana/grafana-pathfinder-app/blob/main/docs/developer/interactive-examples/requirements-reference.md)
- Slack: Pathfinder team guidance (`renderer:website` via conditional wrapper; Tom noted per-block `condition` would be a larger change)
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.