docs: scaffold Video Tutorials page - #322
Conversation
Add a "Video Tutorials" page under Getting Started (Learn group), grouping ~18 planned walkthroughs by persona — getting started, sellers, buyers, catalog, and organizations. Each video is an accordion with a one-line description, a "Coming soon" placeholder, and a link to the matching written guide. A maintainer note at the top carries the exact YouTube embed snippet so recorded videos drop straight in; this page is the single source of truth for video URLs. Wired into docs.json nav. First deliverable for the video-docs initiative (nevermined-io/internal#1091), letting recording and publishing run in parallel.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
There was a problem hiding this comment.
Pull request overview
Scaffolds a new “Video Tutorials” landing page in the Getting Started section to serve as a structured library of upcoming Nevermined App walkthrough videos, with placeholders and links to existing written guides.
Changes:
- Added
getting-started/video-tutorials.mdxwith persona-grouped<Accordion>placeholders and “Written guide” links. - Registered the new page in the Learn group navigation in
docs.json.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| getting-started/video-tutorials.mdx | New tutorials index page with accordion placeholders and links to matching written guides. |
| docs.json | Adds the new page to the Learn navigation list. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| title="VIDEO TITLE" | ||
| frameborder="0" | ||
| allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" | ||
| allowfullscreen | ||
| ></iframe> |
|
👀 Reviewing |
r-marques
left a comment
r-marques
left a comment
There was a problem hiding this comment.
🤖 Automated PR review — 🟡 Mergeable with nits
A clean scaffold: a new getting-started/video-tutorials.mdx (19 accordions, every one a "🎬 Coming soon" placeholder) plus a one-line nav registration. It builds and it doesn't break links — I ran the real gate rather than eyeballing it. The one thing worth fixing before merge is a sentence in the intro <Note> that promises readers something the page doesn't deliver for a third of its entries.
What I reviewed
- Diff range
origin/main...HEAD— 2 files, +154/−0, head12180740. Findings below are my own verification; acode-revieweragent was also running but had not reported by the time I posted, so nothing here rests on it. - Ran
mintlify broken-linksagainst this PR's own tree:success — no broken links found. All 12 internal links (/agents-guide/…,/products/…,/solutions/…,/integrations/…) resolve to real.mdxfiles; I also checked each one individually. Note the check completed rather than aborting early, which additionally rules out the bare-<placeholder>trap that silently voids the whole run. - The two things that most often break this repo are both done right. The maintainer block at
:13uses{/* … */}, not an HTML comment — an HTML comment in MDX fails the Mintlify deploy. Anddocs.jsonis a minimal one-line text insertion into theLearngroup (:45), not a JSON round-trip that reformats ~1300 lines and buries the real change. icon="stripe"is fine, not a missingiconType="brands". I nearly flagged it, then checked: this repo usesicon="python"(another brand icon) 7 times and has noiconTypeanywhere, so bare brand icons are the established, working convention here.- Nav placement sits with the other
getting-started/*pages inLearn, ahead ofproducts/payments/faq— consistent with where a reader would look for it.
On the bigger question — is a page whose every entry is a placeholder ready for the live nav? That's a product call and the PR title says "scaffold", so I'm not treating it as a blocker. The intro <Note> does set the expectation; it just overstates the fallback, which is finding #1.
Verdict: 🟡 Mergeable with nits — 0 blockers, 1 should-fix, 2 nits.
🧭 Inline comments (4)
Each is posted on its line in Files changed.
- 🟡 SHOULD FIX — The Note promises a written guide for every entry — 7 of 19 have none —
getting-started/video-tutorials.mdx:10 - 💡 NIT — "Create a delegation" re-links the enroll-card page when a dedicated delegation page exists —
getting-started/video-tutorials.mdx:101 - 💡 NIT — The page is reachable only from the sidebar — nothing links to it —
docs.json:45 - ✅ NICE — Avoids both of this repo's classic deploy-breakers, and the links actually resolve —
getting-started/video-tutorials.mdx:13
| Prefer to watch instead of read? These short walkthroughs (1–3 minutes each) take you through the Nevermined App screen by screen — signing up, selling your first agent, buying and paying as an agent, and running an organization. | ||
|
|
||
| <Note> | ||
| We're recording this library now. Sections marked **🎬 Coming soon** don't have a video yet — the written guide linked from each one covers the same flow in the meantime. |
There was a problem hiding this comment.
🟡 SHOULD FIX — The Note promises a written guide for every entry — 7 of 19 have none
This sentence tells the reader that for anything marked Coming soon, "the written guide linked from each one covers the same flow in the meantime". That holds for most of the page, but not all of it.
Counted on this file: 19 <Accordion> entries, 12 carry a Written guide link, 7 do not:
| Line | Accordion |
|---|---|
| 39 | Sign up & log in for the first time |
| 43 | Sandbox vs Live |
| 59 | Seller first steps: the dashboard |
| 63 | Connect Stripe |
| 89 | Buyer first steps: dashboard & wallet |
| 108 | See your payment requests |
| 134 | Org plans & org agents |
For those seven a reader gets a title, one sentence, and "🎬 Coming soon" — nothing to click and nothing to read. Since every entry on the page is currently a placeholder, this sentence is the only thing standing between the reader and a dead end, so it's worth it being exactly true.
Two ways to close it, either fine: soften the claim ("where a written guide exists, it's linked below"), or add links for the seven. I looked for existing targets for the gaps and did not find dedicated pages for them — Connect Stripe and Sandbox vs Live appear only as passing mentions inside other guides (e.g. getting-started/overview.mdx, agents-guide/get-api-key.mdx), not as pages I'd send a reader to. So softening the sentence is probably the cheaper fix, unless you know of targets I missed.
🤖 pr-review-toolkit · reviewer-verified · high
| <Accordion title="Create a delegation" icon="user-shield"> | ||
| Delegate a budget to a trusted agent, with limits, so it can pay without you in the loop. | ||
| <Note>🎬 Coming soon</Note> | ||
| **Written guide:** [Enroll a card & delegate a budget](/agents-guide/enroll-card) |
There was a problem hiding this comment.
💡 NIT — "Create a delegation" re-links the enroll-card page when a dedicated delegation page exists
This link and the one under Enroll a payment method (:96) both point at /agents-guide/enroll-card, so two different accordions send the reader to the same page — and someone who clicked specifically for delegation lands on enrolment.
The repo has what looks like the intended target: solutions/card-delegation.mdx, which is nav-registered (docs.json:103), titled "Card Delegation", and described as "Let users enroll a credit or debit card once and delegate a spending budget to AI agents — directly in the app, via a white-labeled redirect, or embedded as a widget." It even carries icon: "user-shield", the same icon you gave this accordion.
Suggest [Card delegation](/solutions/card-delegation) here and leaving :96 as it is.
🤖 pr-review-toolkit · reviewer-verified · medium
| "getting-started/overview", | ||
| "getting-started/core-concepts", | ||
| "getting-started/ai-agent-purchase", | ||
| "getting-started/video-tutorials", |
There was a problem hiding this comment.
💡 NIT — The page is reachable only from the sidebar — nothing links to it
This nav entry is the sole reference to /getting-started/video-tutorials anywhere in the repo; no page links to it. That's normal for a brand-new page, but it means the tutorials are discoverable only by someone already scanning the sidebar.
A line from getting-started/overview.mdx — the page directly above this one in the same Learn group — would put it in the reading flow for someone arriving at the docs for the first time, which is precisely the audience for a "first login" video. Worth doing when the first real recording lands, if not now.
🤖 pr-review-toolkit · reviewer-verified · medium
| We're recording this library now. Sections marked **🎬 Coming soon** don't have a video yet — the written guide linked from each one covers the same flow in the meantime. | ||
| </Note> | ||
|
|
||
| {/* |
There was a problem hiding this comment.
✅ NICE — Avoids both of this repo's classic deploy-breakers, and the links actually resolve
Two traps sidestepped that regularly bite this repo:
- MDX comment style — this block is
{/* … */}. An HTML comment (<!-- … -->) here would fail the Mintlify deploy, and the maintainer instructions inside it are exactly the kind of content that tempts one. docs.jsonas text — the change is a single added line, not ajson.load/json.dumpround-trip that reformats ~1300 lines and hides the real edit in the noise.
And the links hold up: I ran mintlify broken-links against this branch's tree and it returned success — no broken links found, with all 12 internal links independently confirmed to resolve to real files. The run also completed rather than aborting, which rules out a bare <placeholder> voiding the check.
The maintainer block is a genuinely good idea too — the next person to add a video doesn't have to reverse-engineer the embed markup from a rendered page.
🤖 pr-review-toolkit · reviewer-verified · high
r-marques
left a comment
r-marques
left a comment
There was a problem hiding this comment.
🟡 Approved with comments — no blockers; 1 should-fix, 2 nit(s) left inline.
Inline review: #322 (review)
|
🛑 Holding — do not merge yet. This is the scaffold only; the accordions are |
Why this matters
New users learn the Nevermined App fastest by watching, not reading — especially the UI-heavy first-run flows (signing up, connecting Stripe, enrolling a card, delegating a budget) that our written docs cover only lightly. This PR lays the foundation for a video tutorial library: a single docs page that groups every planned walkthrough by persona and is ready to drop YouTube embeds into. It lets recording and publishing proceed in parallel and gives the app team one place to source video URLs from.
This is the first shippable deliverable for the video-documentation initiative (internal#1091).
What's in this PR
getting-started/video-tutorials.mdx, added to the Learn group indocs.json(right after "Buy & call a paid agent").<Accordion>with a one-line description, a 🎬 Coming soon placeholder, and a link to the matching written guide where one exists.<Frame><iframe .../>YouTube embed snippet, so a recorded video swaps in with a one-line edit. This page is the single source of truth for video URLs (in-app and modal embeds reuse them).Structure and priorities were scoped by walking nevermined.app and cross-referencing the current docs — see the plan of attack on internal#1091.
Test plan
docs.jsonis valid JSON.mintlify broken-links— no broken links (all "written guide" targets verified).🤖 Generated with Claude Code
https://claude.ai/code/session_01JiUd16wyGJ1CTGdwzFNxFR