grafana / grafana/interactive-tutorials

Adopt renderer:website conditions for website-only media blocks

Open
#481 0 comments 0 reactions 1 assignee Claimed by @tacole02 View on GitHub
enhancement lh-learning-path
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.