feat: add Basics learning category with YouTube tutorials (#15436)

## Summary

Adds a "Basics" category (first in nav) to /learning with two beginner
YouTube tutorials, teaching /learning to play YouTube embeds alongside
self-hosted MP4s.

## Changes

- **What**: New `basics` `LearningCategory` (nav-first) with two
tutorials from the official ComfyUI channel. `LearningTutorial` now
supports `youtubeId?` (YouTube embed) in addition to `videoSrc?`
(self-hosted); exactly one is set. When `youtubeId` is present,
`LearningWatchPage` renders a new `LearningVideoEmbed.vue`
(youtube-nocookie iframe, `?autoplay=1&mute=1&rel=0`, mirroring
`HeroLivestream01`) instead of `VideoPlayer`, which is left untouched.
Posters use YouTube thumbnails. `VideoObject` JSON-LD gains `embedUrl`
(and `contentUrl` becomes optional) for embedded items. New
`tags.fundamentals/nodeGraph/lora/controlNet` and full en + zh-CN
category copy.
- **Breaking**: `LearningTutorial.videoSrc` and
`VideoObjectInput.contentUrl` are now optional. Extensions/consumers of
learning data must branch on `youtubeId` rather than assume `videoSrc`
exists.

## Review Focus

- `videoSrc`/`youtubeId` exactly-one invariant (unit-tested in
`learningTutorials.test.ts`).
- JSON-LD mapping for embedded videos: `embedUrl` = nocookie embed,
`contentUrl` = canonical watch URL.
- Posters use `img.youtube.com/vi/<id>/maxresdefault.jpg`; if any
thumbnail 404s, `hqdefault.jpg` is the always-present fallback.
- Playwright was not run locally (multi-worktree dev-server/port
contention); it will run in CI. Verified via `vitest` (8 passed) +
`astro check` (0 errors) + lint/format.

Author: imick-io

apps/website/e2e/learning.spec.ts

@@ -26,6 +26,12 @@ const categoryNav = (page: Page, locale: 'en' | 'zh-CN' = 'en') =>
 // metadata helpers, so these assertions catch a regression in the helpers or
 // the underlying strings — not just the wiring.
 const EXPECTED_META = {
+  basics: {
+    heading: 'ComfyUI Basics',
+    description:
+      'Beginner ComfyUI tutorials — learn the node graph, LoRAs, style transfer, and ControlNets from the ground up.',
+    title: 'ComfyUI Basics - Comfy'
+  },
   vfx: {
     heading: 'VFX Tutorials',
     description:
@@ -108,41 +114,34 @@ test.describe('Learning page @smoke', () => {
     }
   })
 
-  test('tutorials with a workflow link expose an external Try Workflow link', async ({
+  test('tutorials with a CTA link expose their labelled external link', async ({
     page
   }) => {
     const linkedTutorials = learningTutorials.filter(
       (tutorial) => tutorial.href
     )
-    const workflowLinks = page.getByRole('link', {
-      name: t('cta.tryWorkflow', 'en')
-    })
-    const hrefs = await workflowLinks.evaluateAll((links) =>
-      links.map((link) => link.getAttribute('href'))
-    )
+    expect(linkedTutorials.length).toBeGreaterThan(0)
     for (const tutorial of linkedTutorials) {
-      expect(hrefs).toContain(tutorial.href)
+      const link = page.locator(`a[href="${tutorial.href}"]`)
+      await expect(link).toContainText(
+        t(tutorial.ctaLabelKey ?? 'cta.tryWorkflow', 'en')
+      )
     }
   })
 
-  test('newTab tutorials open their workflow link in a new tab', async ({
+  test('newTab tutorials open their CTA link in a new tab', async ({
     page
   }) => {
-    const links = page.getByRole('link', { name: t('cta.tryWorkflow', 'en') })
-    const attrs = await links.evaluateAll((elements) =>
-      elements.map((element) => ({
-        href: element.getAttribute('href') ?? '',
-        target: element.getAttribute('target')
-      }))
-    )
-    // The page-level CTA shares the label; only judge tutorial links.
-    const tutorialAttrs = attrs.filter(({ href }) =>
-      learningTutorials.some((item) => item.href === href)
+    const linkedTutorials = learningTutorials.filter(
+      (tutorial) => tutorial.href
     )
-    expect(tutorialAttrs.length).toBeGreaterThan(0)
-    for (const { href, target } of tutorialAttrs) {
-      const tutorial = learningTutorials.find((item) => item.href === href)
-      expect(target, href).toBe(tutorial?.newTab ? '_blank' : null)
+    for (const tutorial of linkedTutorials) {
+      const link = page.locator(`a[href="${tutorial.href}"]`)
+      if (tutorial.newTab) {
+        await expect(link).toHaveAttribute('target', '_blank')
+      } else {
+        await expect(link).not.toHaveAttribute('target', '_blank')
+      }
     }
   })
 
@@ -239,6 +238,16 @@ test.describe('Learning category pages @smoke', () => {
 
 test.describe('Learning tutorial page @smoke', () => {
   const [firstTutorial] = learningTutorials
+  const selfHostedTutorial = learningTutorials.find(
+    (tutorial) => tutorial.videoSrc && !tutorial.youtubeId
+  )
+  const youtubeTutorial = learningTutorials.find(
+    (tutorial) => tutorial.youtubeId
+  )
+  const workflowTutorial = learningTutorials.find((tutorial) => tutorial.href)
+  if (!selfHostedTutorial || !youtubeTutorial || !workflowTutorial) {
+    throw new Error('expected self-hosted, youtube, and workflow tutorials')
+  }
 
   test('a thumbnail navigates to the dedicated tutorial page', async ({
     page
@@ -257,10 +266,10 @@ test.describe('Learning tutorial page @smoke', () => {
   test('the page exposes an indexable heading and autoplay video', async ({
     page
   }) => {
-    await page.goto(tutorialPath(firstTutorial))
+    await page.goto(tutorialPath(selfHostedTutorial))
 
     await expect(page.getByRole('heading', { level: 1 })).toHaveText(
-      firstTutorial.title.en
+      selfHostedTutorial.title.en
     )
     // Attribute-level autoplay check: blockExternalMedia aborts the video
     // request, so actual playback never starts in e2e.
@@ -270,6 +279,20 @@ test.describe('Learning tutorial page @smoke', () => {
     await expect(video).toHaveAttribute('muted', '')
   })
 
+  test('youtube tutorials embed a nocookie iframe instead of a video', async ({
+    page
+  }) => {
+    await page.goto(tutorialPath(youtubeTutorial))
+
+    await expect(page.locator('video')).toHaveCount(0)
+    const iframe = page.locator('iframe[src*="youtube-nocookie.com/embed/"]')
+    await expect(iframe).toBeVisible()
+    await expect(iframe).toHaveAttribute(
+      'src',
+      new RegExp(`/embed/${youtubeTutorial.youtubeId}\\b`)
+    )
+  })
+
   test('the breadcrumb links back to the directory and category', async ({
     page
   }) => {
@@ -301,12 +324,13 @@ test.describe('Learning tutorial page @smoke', () => {
     }
   })
 
-  test('links to the workflow from the title block', async ({ page }) => {
-    if (!firstTutorial.href) throw new Error('expected a workflow link')
-    await page.goto(tutorialPath(firstTutorial))
+  test('links to the CTA target from the title block', async ({ page }) => {
+    await page.goto(tutorialPath(workflowTutorial))
 
-    const workflowLink = page.locator(`a[href="${firstTutorial.href}"]`)
-    await expect(workflowLink).toHaveText(t('cta.tryWorkflow', 'en'))
+    const ctaLink = page.locator(`a[href="${workflowTutorial.href}"]`)
+    await expect(ctaLink).toHaveText(
+      t(workflowTutorial.ctaLabelKey ?? 'cta.tryWorkflow', 'en')
+    )
   })
 
   test('the chapter strip links to same-category siblings', async ({

apps/website/src/components/learning/FeaturedTutorialCard.vue

@@ -56,7 +56,7 @@ const { tutorial, locale = 'en' } = defineProps<{
           size="default"
           class="ps-0"
         >
-          {{ t('cta.tryWorkflow', locale) }}
+          {{ t(tutorial.ctaLabelKey ?? 'cta.tryWorkflow', locale) }}
         </ButtonPill>
       </div>
     </div>

apps/website/src/components/learning/LearningTutorialPage.astro

@@ -9,7 +9,8 @@ import { externalLinks, localizeHref } from '../../config/routes'
 import type { LearningTutorial } from '../../data/learningTutorials'
 import {
   learningCrumbs,
-  tutorialDescription
+  tutorialDescription,
+  youtubeEmbedUrl
 } from '../../data/learningTutorials'
 import type { JsonLdNode } from '../../utils/jsonLd'
 import {
@@ -43,6 +44,9 @@ const video: JsonLdNode = videoObjectNode({
   description,
   thumbnailUrl: tutorial.poster,
   contentUrl: tutorial.videoSrc,
+  embedUrl: tutorial.youtubeId
+    ? youtubeEmbedUrl(tutorial.youtubeId)
+    : undefined,
   uploadDate: tutorial.publishedDate,
   locale
 })

apps/website/src/components/learning/LearningVideoEmbed.test.ts

@@ -0,0 +1,27 @@
+// @vitest-environment happy-dom
+import { render, screen } from '@testing-library/vue'
+import { describe, expect, it } from 'vitest'
+
+import LearningVideoEmbed from './LearningVideoEmbed.vue'
+
+function renderEmbed(youtubeId = 'TQhIYT1ZYGQ', title = 'Node Graph Basics') {
+  render(LearningVideoEmbed, { props: { youtubeId, title } })
+  return screen.getByTitle(title)
+}
+
+describe('LearningVideoEmbed', () => {
+  it('embeds the privacy-friendly nocookie player for the given id', () => {
+    const iframe = renderEmbed('abc123', 'Full Node Graph Basics')
+
+    expect(iframe.getAttribute('src')).toBe(
+      'https://www.youtube-nocookie.com/embed/abc123?autoplay=1&mute=1&rel=0'
+    )
+  })
+
+  it('lazy-loads the titled frame and allows fullscreen', () => {
+    const iframe = renderEmbed('abc123', 'Full Node Graph Basics')
+
+    expect(iframe.getAttribute('loading')).toBe('lazy')
+    expect(iframe.hasAttribute('allowfullscreen')).toBe(true)
+  })
+})

apps/website/src/components/learning/LearningVideoEmbed.vue

@@ -0,0 +1,37 @@
+<script setup lang="ts">
+import type { HTMLAttributes } from 'vue'
+
+import { cn } from '@comfyorg/tailwind-utils'
+
+import { youtubeEmbedUrl } from '../../data/learningTutorials'
+
+const {
+  youtubeId,
+  title,
+  class: className
+} = defineProps<{
+  youtubeId: string
+  title: string
+  class?: HTMLAttributes['class']
+}>()
+</script>
+
+<template>
+  <div
+    :class="
+      cn(
+        'relative aspect-video overflow-hidden rounded-4xl border border-white/10 bg-black',
+        className
+      )
+    "
+  >
+    <iframe
+      :src="youtubeEmbedUrl(youtubeId)"
+      :title
+      class="size-full"
+      loading="lazy"
+      allow="autoplay; encrypted-media; picture-in-picture; fullscreen"
+      allowfullscreen
+    />
+  </div>
+</template>

apps/website/src/components/learning/LearningWatchPage.test.ts

@@ -0,0 +1,47 @@
+// @vitest-environment happy-dom
+import { render, screen } from '@testing-library/vue'
+import { describe, expect, it } from 'vitest'
+
+import type { LearningTutorial } from '../../data/learningTutorials'
+
+import { filterByCategory } from '../../data/learningTutorials'
+import LearningWatchPage from './LearningWatchPage.vue'
+
+const youtubeTutorial = filterByCategory('basics').find(
+  (tutorial) => tutorial.youtubeId !== undefined
+)
+if (!youtubeTutorial)
+  throw new Error('Expected a Basics tutorial with youtubeId')
+
+const hostedTutorial = filterByCategory('vfx').find(
+  (tutorial) => tutorial.videoSrc !== undefined
+)
+if (!hostedTutorial) throw new Error('Expected a VFX tutorial with videoSrc')
+
+const stubs = {
+  LearningVideoEmbed: { template: '<div data-testid="youtube-embed" />' },
+  VideoPlayer: { template: '<div data-testid="hosted-video" />' }
+}
+
+function renderWatchPage(tutorial: LearningTutorial) {
+  render(LearningWatchPage, {
+    props: { tutorial, locale: 'en' },
+    global: { stubs }
+  })
+}
+
+describe('LearningWatchPage', () => {
+  it('embeds the YouTube player for tutorials with a youtubeId', () => {
+    renderWatchPage(youtubeTutorial)
+
+    expect(screen.getByTestId('youtube-embed')).toBeTruthy()
+    expect(screen.queryByTestId('hosted-video')).toBeNull()
+  })
+
+  it('falls back to the hosted VideoPlayer for self-hosted tutorials', () => {
+    renderWatchPage(hostedTutorial)
+
+    expect(screen.getByTestId('hosted-video')).toBeTruthy()
+    expect(screen.queryByTestId('youtube-embed')).toBeNull()
+  })
+})

apps/website/src/components/learning/LearningWatchPage.vue

@@ -18,6 +18,7 @@ import WatchPageLayout from '../blocks/WatchPageLayout.vue'
 import WatchRecommendedCard from '../blocks/WatchRecommendedCard.vue'
 import Button from '../ui/button/Button.vue'
 import VideoPlayer from '../common/VideoPlayer.vue'
+import LearningVideoEmbed from './LearningVideoEmbed.vue'
 import Badge from '../ui/badge/Badge.vue'
 
 const { tutorial, locale = 'en' } = defineProps<{
@@ -59,7 +60,15 @@ const recommended = recommendedFor(tutorial).map((item) => ({
     :read-more-label="t('ui.readMore', locale)"
     :read-less-label="t('ui.readLess', locale)"
   >
+    <LearningVideoEmbed
+      v-if="tutorial.youtubeId"
+      :key="tutorial.id"
+      :youtube-id="tutorial.youtubeId"
+      :title="tutorial.title[locale]"
+      class="w-full"
+    />
     <VideoPlayer
+      v-else
       :key="tutorial.id"
       :locale
       :src="tutorial.videoSrc"
@@ -93,8 +102,9 @@ const recommended = recommendedFor(tutorial).map((item) => ({
         size="sm"
         :href="tutorial.href"
         :target="tutorial.newTab ? '_blank' : undefined"
+        :rel="tutorial.newTab ? 'noopener noreferrer' : undefined"
       >
-        {{ t('cta.tryWorkflow', locale) }}
+        {{ t(tutorial.ctaLabelKey ?? 'cta.tryWorkflow', locale) }}
       </Button>
     </template>
 

apps/website/src/components/learning/TutorialRow.vue

@@ -67,7 +67,7 @@ const { tutorial, locale = 'en' } = defineProps<{
       size="default"
       class="ps-0"
     >
-      {{ t('cta.tryWorkflow', locale) }}
+      {{ t(tutorial.ctaLabelKey ?? 'cta.tryWorkflow', locale) }}
     </ButtonPill>
   </li>
 </template>

apps/website/src/data/learningTutorials.test.ts

@@ -5,7 +5,8 @@ import {
   filterByCategory,
   learningCategories,
   learningTutorials,
-  recommendedFor
+  recommendedFor,
+  youtubeEmbedUrl
 } from './learningTutorials'
 
 const firstVfx = filterByCategory('vfx')[0]
@@ -42,6 +43,36 @@ describe('categoryChapters', () => {
   })
 })
 
+describe('video source', () => {
+  it('plays via exactly one of videoSrc or youtubeId', () => {
+    for (const tutorial of learningTutorials) {
+      expect(Boolean(tutorial.videoSrc) !== Boolean(tutorial.youtubeId)).toBe(
+        true
+      )
+    }
+  })
+
+  it('builds a privacy-friendly nocookie embed URL from an id', () => {
+    expect(youtubeEmbedUrl('abc123')).toBe(
+      'https://www.youtube-nocookie.com/embed/abc123?autoplay=1&mute=1&rel=0'
+    )
+  })
+})
+
+describe('basics CTA', () => {
+  it('sends basics tutorials to cloud signup with a Try for Free label', () => {
+    const basics = filterByCategory('basics')
+    expect(basics.length).toBeGreaterThan(0)
+    for (const tutorial of basics) {
+      expect(tutorial.href).toMatch(
+        /^https:\/\/cloud\.comfy\.org\/\?.*utm_campaign=free_tier.*utm_content=learning_basics_/
+      )
+      expect(tutorial.newTab).toBe(true)
+      expect(tutorial.ctaLabelKey).toBe('cta.tryForFree')
+    }
+  })
+})
+
 describe('recommendedFor', () => {
   it('only recommends tutorials from other categories', () => {
     const recommended = recommendedFor(firstVfx)