From f0dd474f0637b1bcb01b8608df60c613d4239779 Mon Sep 17 00:00:00 2001 From: Charly Abraham Date: Wed, 11 Nov 2026 23:49:39 +0530 Subject: [PATCH 1/2] Add dedicated watch pages for image tutorials --- docs/10-Tutorials/01-add-images.md | 28 +---- scripts/verify-tutorials.cjs | 40 ++++++- src/components/Video/ImageTutorialVideo.js | 30 +++++ src/components/Video/ImageWatchPage.js | 41 +++++++ .../Video/ImageWatchPage.module.css | 104 ++++++++++++++++++ src/data/image-tutorial-videos.json | 54 +++++++++ .../videos/add-image-phoenix-community.js | 6 + src/pages/videos/add-image-phoenix-pro.js | 6 + 8 files changed, 283 insertions(+), 26 deletions(-) create mode 100644 src/components/Video/ImageTutorialVideo.js create mode 100644 src/components/Video/ImageWatchPage.js create mode 100644 src/components/Video/ImageWatchPage.module.css create mode 100644 src/data/image-tutorial-videos.json create mode 100644 src/pages/videos/add-image-phoenix-community.js create mode 100644 src/pages/videos/add-image-phoenix-pro.js diff --git a/docs/10-Tutorials/01-add-images.md b/docs/10-Tutorials/01-add-images.md index 8799dace8..085eba033 100644 --- a/docs/10-Tutorials/01-add-images.md +++ b/docs/10-Tutorials/01-add-images.md @@ -10,7 +10,7 @@ toc_max_heading_level: 2 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import TutorialIcon from '@site/src/components/TutorialIcon'; -import TutorialVideo from '@site/src/components/Video/TutorialVideo'; +import ImageTutorialVideo from '@site/src/components/Video/ImageTutorialVideo'; You can add your own photo to an HTML page in either edition of **Phoenix Code**: @@ -56,18 +56,7 @@ Choose your edition below. In **Phoenix Pro**, choose a replacement picture dire This recording uses `first-website` in **Design Mode** from start to finish. Your computer's file picker opens outside the recorded browser view. - - - - Watch the Phoenix Pro walkthrough. - + ### Turn on visual editing @@ -125,18 +114,7 @@ For the steps below, we'll use the name `photo.jpg`. If your file is named `holi This 31-second recording starts with `photo.jpg` already copied into the project's `images` folder. - - - - Watch the Community walkthrough. - + ### Find the picture's HTML diff --git a/scripts/verify-tutorials.cjs b/scripts/verify-tutorials.cjs index 07f6cf1e4..fc6bd381a 100644 --- a/scripts/verify-tutorials.cjs +++ b/scripts/verify-tutorials.cjs @@ -7,6 +7,7 @@ const {unzipSync} = require('fflate'); const robotsParser = require('robots-parser'); const {TUTORIALS, PROJECTS, projectFiles} = require('./package-tutorials.cjs'); const {PUBLICATIONS_PATH, validatePublications} = require('../plugins/tutorial-media/publications'); +const imageVideos = require('../src/data/image-tutorial-videos.json'); const SITE = path.join(__dirname, '..'); const ORIGIN = 'https://docs.phcode.dev'; @@ -120,6 +121,7 @@ function verify(build, release = false) { assert.equal(videos.length, captures.recordings.length, 'Every recorded video must have a player and metadata'); assert.equal(new Set(videos.map(({schema}) => schema.contentUrl)).size, videos.length, 'Video sources must be distinct'); assert.equal(new Set(videos.map(({schema}) => schema.name)).size, videos.length, 'Video names must be distinct'); + const captionTextBySource = new Map(); for (const {schema, document} of videos) { const source = new URL(schema.contentUrl).pathname; const player = document('article video').toArray().find(element => document(element).find('source').attr('src') === source); @@ -142,6 +144,7 @@ function verify(build, release = false) { assert(captions.startsWith('WEBVTT'), `Invalid caption format: ${source}`); const cues = [...captions.matchAll(/(\d{2}:\d{2}:\d{2}\.\d{3}) --> (\d{2}:\d{2}:\d{2}\.\d{3})\n([^\n]+)/g)]; assert(cues.length, `Missing video captions: ${source}`); + captionTextBySource.set(source, cues.map(cue => cue[3])); const seconds = stamp => { const [hours, minutes, value] = stamp.split(':').map(Number); return hours * 3600 + minutes * 60 + value; @@ -154,6 +157,41 @@ function verify(build, release = false) { } } + for (const video of Object.values(imageVideos)) { + const route = video.watchPath; + const document = page(target(route)); + assert(indexed.has(ORIGIN + route), `Watch page missing from sitemap: ${route}`); + assert.equal(document('main h1').length, 1, `Expected one watch-page title: ${route}`); + assert.deepEqual(document('link[rel="canonical"]').map((_, el) => document(el).attr('href')).get(), + [ORIGIN + route], `Watch page must have its own canonical URL: ${route}`); + document('meta[name="robots"], meta[name="googlebot"]').each((_, el) => { + assert(!/noindex/i.test(document(el).attr('content') || ''), `Watch page marked noindex: ${route}`); + }); + // A watch page must serve one player in the initial HTML, outside tabs or + // expandable sections. Google still decides whether to index the video. + assert.equal(document('video').length, 1, `Expected one video per watch page: ${route}`); + const player = document('main video'); + assert.equal(player.length, 1, `Watch-page player missing from main content: ${route}`); + assert.equal(player.closest('[hidden], [role="tabpanel"], details').length, 0, + `Watch-page player requires an interaction to appear: ${route}`); + assert.equal(player.find('source').attr('src'), video.source, `Wrong watch-page recording: ${route}`); + const schemas = document('script[type="application/ld+json"]').toArray() + .map(el => JSON.parse(document(el).text())).filter(schema => schema['@type'] === 'VideoObject'); + assert.equal(schemas.length, 1, `Expected one watch-page VideoObject: ${route}`); + const original = videos.find(({schema}) => new URL(schema.contentUrl).pathname === video.source); + assert(original, `Watch page has no corresponding tutorial recording: ${route}`); + assert.deepEqual(schemas[0], original.schema, `Watch-page metadata differs from its tutorial: ${route}`); + assert.equal(player.attr('poster'), new URL(schemas[0].thumbnailUrl[0]).pathname, `Watch-page poster mismatch: ${route}`); + assert.equal(player.find('track[kind="captions"]').attr('src'), video.captions, `Watch-page captions missing: ${route}`); + assert(imagePage('article a').toArray().some(el => imagePage(el).attr('href') === route), + `Tutorial does not link to watch page: ${route}`); + assert(document('main a').toArray().some(el => document(el).attr('href') === video.guidePath), + `Watch page does not link to its edition's tutorial: ${route}`); + target(video.guidePath); + assert.deepEqual(document('main details li').map((_, el) => document(el).text()).get(), + captionTextBySource.get(video.source), `Watch-page instructions differ from the video captions: ${route}`); + } + let indexLinks = 0; for (const filename of ['llms.txt', 'api/llms.txt']) { const index = fs.readFileSync(path.join(build, filename), 'utf8'); @@ -172,7 +210,7 @@ function verify(build, release = false) { assert(Buffer.from(archive[`${project}/${name}`]).equals(content), `Stale practice file: ${project}/${name}`); } } - return `PASS: ${GUIDES.length} guides, local links and anchors, screenshots, 5 image FAQs, ${videos.length} videos with captions, ${indexLinks} AI-index links, and both practice ZIPs.` + + return `PASS: ${GUIDES.length} guides, local links and anchors, screenshots, 5 image FAQs, ${videos.length} videos with captions, ${Object.keys(imageVideos).length} video watch pages, ${indexLinks} AI-index links, and both practice ZIPs.` + (release ? ' Release publication dates are complete.' : ' Preview metadata verified.'); } diff --git a/src/components/Video/ImageTutorialVideo.js b/src/components/Video/ImageTutorialVideo.js new file mode 100644 index 000000000..6eda071b9 --- /dev/null +++ b/src/components/Video/ImageTutorialVideo.js @@ -0,0 +1,30 @@ +import React from 'react'; +import Link from '@docusaurus/Link'; +import TutorialVideo from './TutorialVideo'; +import videos from '@site/src/data/image-tutorial-videos.json'; +import styles from './ImageWatchPage.module.css'; + +// Keep the article and watch page tied to the same recording and metadata. +export default function ImageTutorialVideo({edition, className, showWatchLink = false}) { + const video = videos[edition]; + return <> + + + Watch the {edition === 'pro' ? 'Phoenix Pro' : 'Community'} walkthrough. + + {showWatchLink &&
+ + Open video + + +
} + ; +} diff --git a/src/components/Video/ImageWatchPage.js b/src/components/Video/ImageWatchPage.js new file mode 100644 index 000000000..9c9f511d6 --- /dev/null +++ b/src/components/Video/ImageWatchPage.js @@ -0,0 +1,41 @@ +import React from 'react'; +import Layout from '@theme/Layout'; +import Head from '@docusaurus/Head'; +import Link from '@docusaurus/Link'; +import {useBaseUrlUtils} from '@docusaurus/useBaseUrl'; +import ImageTutorialVideo from './ImageTutorialVideo'; +import videos from '@site/src/data/image-tutorial-videos.json'; +import styles from './ImageWatchPage.module.css'; + +export default function ImageWatchPage({edition}) { + const video = videos[edition]; + const {withBaseUrl} = useBaseUrlUtils(); + const poster = withBaseUrl(video.poster, {absolute: true}); + const seconds = Math.round(Number(video.metadata.duration.slice(2, -1))); + + return + + + + +
+
+
+

{video.title}

+

{seconds} seconds · On-screen instructions

+
+ +
+

{video.context}

+

Read the full tutorial and get the practice website

+
+ Read the video’s on-screen instructions +
    + {video.instructions.map(instruction =>
  1. {instruction}
  2. )} +
+
+
+
+
+
; +} diff --git a/src/components/Video/ImageWatchPage.module.css b/src/components/Video/ImageWatchPage.module.css new file mode 100644 index 000000000..512336f45 --- /dev/null +++ b/src/components/Video/ImageWatchPage.module.css @@ -0,0 +1,104 @@ +.main { + width: 100%; + max-width: 64rem; + margin-inline: auto; + padding: 2rem 1.25rem 3rem; +} + +.main h1 { + font-size: 2rem; + text-wrap: balance; + margin-bottom: 0.5rem; +} + +.duration { + color: var(--ifm-color-content-secondary); + margin-bottom: 1rem; +} + +.player { + display: block; + max-height: 70vh; + object-fit: contain; + background: #000; +} + +.description { + max-width: 72ch; + margin-top: 1.5rem; +} + +.links { + --ifm-link-color: var(--ifm-color-primary-darker); + --ifm-link-hover-color: var(--ifm-color-primary-darkest); +} + +[data-theme='dark'] .links { + --ifm-link-color: var(--ifm-color-primary); + --ifm-link-hover-color: var(--ifm-color-primary); +} + +.links a { + text-decoration: underline; + text-underline-offset: 0.15em; +} + +.watchAction { + display: flex; + justify-content: flex-end; + margin-bottom: 0.25rem; +} + +.watchAction a { + display: inline-flex; + align-items: center; + gap: 0.375rem; + min-height: 2.75rem; + padding-inline: 0.25rem; + color: var(--ifm-color-content-secondary); + font-size: 0.875rem; + text-decoration: none; +} + +.watchAction a:hover { + color: var(--ifm-font-color-base); + text-decoration: underline; + text-underline-offset: 0.15em; +} + +.watchAction a:focus-visible { + outline: 2px solid currentColor; + outline-offset: 2px; +} + +.watchAction svg { + flex-shrink: 0; +} + +.transcript summary { + cursor: pointer; + padding-block: 0.5rem; +} + +.transcript summary:focus-visible { + outline: 2px solid currentColor; + outline-offset: 3px; +} + +.transcript ol { + margin-top: 0.75rem; +} + +.transcript li + li { + margin-top: 0.5rem; +} + +@media (max-width: 600px) { + .main { + padding: 1.25rem 1rem 2rem; + } + + .main h1 { + font-size: 1.75rem; + } +} diff --git a/src/data/image-tutorial-videos.json b/src/data/image-tutorial-videos.json new file mode 100644 index 000000000..c3c2f792c --- /dev/null +++ b/src/data/image-tutorial-videos.json @@ -0,0 +1,54 @@ +{ + "pro": { + "watchPath": "/videos/add-image-phoenix-pro", + "guidePath": "/docs/tutorials/add-images?edition=pro", + "title": "Add an image in Phoenix Pro", + "context": "This walkthrough starts with the first-website practice project open in Design Mode. Your computer’s file picker opens outside the recording.", + "source": "/tutorials/media/pro-add-image-complete.mp4", + "poster": "/tutorials/media/pro-image-gallery.png", + "captions": "/tutorials/media/pro-add-image-complete.vtt", + "label": "Phoenix Pro walkthrough: choose a photo from your device and set its description in first-website", + "metadata": { + "name": "Add an image in Phoenix Pro using Design Mode", + "description": "Replace the picture in the first-website practice project using Phoenix Pro. Open Image Gallery in Design Mode, select a photo from your device, set its alt description in Element Properties, and save.", + "duration": "PT38.28S", + "dateCreated": "2026-11-10" + }, + "instructions": [ + "Phoenix Pro: open first-website in Design Mode for a larger preview.", + "Click the grey pen to turn on Edit Mode. An orange pen means editing is on.", + "Click the hills. The Image Gallery opens at the bottom.", + "Click Select from device, then choose photo.jpg in your file picker.", + "If asked where to save the picture, enter images and click OK.", + "Click the photo, close the Image Gallery, then click img to open its properties.", + "Scroll inside Element Properties to show all the Attributes.", + "Replace the alt text with a short description. Press Enter to apply it.", + "Click Save File in the narrow toolbar on the left. Stay in Design Mode.", + "Click the orange pen to turn editing off and check the finished page.", + "Your photo and description are saved. The image is inside your project." + ] + }, + "community": { + "watchPath": "/videos/add-image-phoenix-community", + "guidePath": "/docs/tutorials/add-images?edition=community", + "title": "Add an image in Phoenix Code Community", + "context": "This walkthrough uses the free Community features. It starts with photo.jpg already copied into the first-website project’s images folder.", + "source": "/tutorials/media/community-add-image.mp4", + "poster": "/tutorials/media/community-select-image-tag.png", + "captions": "/tutorials/media/community-add-image.vtt", + "label": "Community walkthrough: replace an image using Highlight Mode in first-website", + "metadata": { + "name": "Add an image in Phoenix Code Community using Highlight Mode", + "description": "Replace the picture in the first-website practice project using free Community features. Use Highlight Mode to locate the image in HTML, select the whole img tag, replace its filename and alt description, and save.", + "duration": "PT31.16S", + "dateCreated": "2026-11-10" + }, + "instructions": [ + "Community: choose Highlight Mode from the arrow beside the pen.", + "Click the hills in Live Preview. The editor finds the image tag.", + "In the editor, select the whole image tag before replacing it.", + "Paste the new tag. Use your picture filename and a short description.", + "Save with Ctrl+S (Windows/Linux) or Cmd+S (Mac). Your photo is in the page." + ] + } +} diff --git a/src/pages/videos/add-image-phoenix-community.js b/src/pages/videos/add-image-phoenix-community.js new file mode 100644 index 000000000..5db859ec8 --- /dev/null +++ b/src/pages/videos/add-image-phoenix-community.js @@ -0,0 +1,6 @@ +import React from 'react'; +import ImageWatchPage from '@site/src/components/Video/ImageWatchPage'; + +export default function CommunityImageVideoPage() { + return ; +} diff --git a/src/pages/videos/add-image-phoenix-pro.js b/src/pages/videos/add-image-phoenix-pro.js new file mode 100644 index 000000000..956bdf6de --- /dev/null +++ b/src/pages/videos/add-image-phoenix-pro.js @@ -0,0 +1,6 @@ +import React from 'react'; +import ImageWatchPage from '@site/src/components/Video/ImageWatchPage'; + +export default function ProImageVideoPage() { + return ; +} From 20f73e7e01e8d982a2ef85203259adf688ac3a74 Mon Sep 17 00:00:00 2001 From: Charly Abraham Date: Wed, 11 Nov 2026 23:55:04 +0530 Subject: [PATCH 2/2] docs: document tutorial video and watch-page workflow --- AGENTS.md | 12 +++++ CONTRIBUTING.md | 121 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 4 ++ 3 files changed, 137 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..380c668d2 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,12 @@ +# Guidance for AI contributors + +Before adding or changing tutorial recordings, video players, video metadata, +or watch pages, read the +[video contributor notes](CONTRIBUTING.md#adding-or-updating-tutorial-videos). +They explain how to preserve the article's reading experience, reuse the video +and its metadata on a dedicated watch page, and retain original publication dates. + +Keep verification code in JavaScript. For video or implementation changes, follow +the [tutorial release checks](README.md#tutorial-release-checks) and the visual +checks in the contributor notes. For notes-only edits, review links and the diff; +a website rebuild is unnecessary. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bff9c8473..eaae8e491 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,6 +4,7 @@ 1. [About the Project](#about-the-project) 1. [Project Status](#project-status) 1. [Getting Started](#getting-started) +1. [Adding or updating tutorial videos](#adding-or-updating-tutorial-videos) ## Community engagement 1. [Code of Conduct](https://github.com/phcode-dev/docs/blob/main/CODE_OF_CONDUCT.md) @@ -22,3 +23,123 @@ Documentation for phoenix/brackets # Getting Started * see https://github.com/phcode-dev/docs/blob/main/README.md + +# Adding or updating tutorial videos + +Use these notes when adding recordings, changing a video player, or creating a +page for watching a tutorial video. They apply to human contributors and AI agents. + +## Why we have separate watch pages + +The written tutorial remains a complete guide with supporting videos. When a +recording also deserves its own viewing experience and discovery in video search, +give it a dedicated watch page where the video is the main content. +[Google's video guidance](https://developers.google.com/search/docs/appearance/video#create-a-dedicated-watch-page) +allows the same video on both pages; metadata alone does not make an article a +watch page. + +Search Console may still report **Video isn't on a watch page** for the article. +That is expected when its video is supplementary and does not mean the article +cannot be indexed as a normal web page. Check the separate watch URL for video +indexing. See [Google's video indexing report documentation](https://support.google.com/webmasters/answer/9495631?hl=en). + +## Preserve the reading experience + +- Keep the article's written steps, screenshots, edition tabs, and inline videos + in their useful positions. Keep Pro first and selected by default where both + Pro and Community workflows are documented. +- Under an inline video with a watch page, use the existing small, right-aligned + **Open video →** link. Keep its descriptive accessible label, visible keyboard + focus, and touch target. Avoid a prominent extra callout or a sentence about + watching the video "on its own page." +- The link must be a real crawlable link to the watch page. It opens a page, so + do not label it "Fullscreen." +- Reuse `TutorialVideo` for playback: silent autoplay when visible, native + controls, pause offscreen, respect a reader's pause and reduced-motion setting, + and no automatic loop. Browser autoplay restrictions may require pressing Play. +- On the watch page, show one prominent video near the top, available in the + initial HTML without opening a tab or expandable section. Follow it with brief + context, a link back to the relevant article edition, and expandable on-screen + instructions. Keep the article and watch page at their own canonical URLs. + +## Files to use as the reference + +The image tutorial is the existing example: + +| File | Responsibility | +| --- | --- | +| [TutorialVideo.js](src/components/Video/TutorialVideo.js) | Shared playback behavior and `VideoObject` generated from the actual media URLs. | +| [image-tutorial-videos.json](src/data/image-tutorial-videos.json) | Shared recording details, metadata, watch and guide paths, and on-screen instructions for both image editions. | +| [ImageTutorialVideo.js](src/components/Video/ImageTutorialVideo.js) | Reuses the same recording in the article and watch page; `showWatchLink` adds **Open video →** in the article. | +| [ImageWatchPage.js](src/components/Video/ImageWatchPage.js) and [its styles](src/components/Video/ImageWatchPage.module.css) | Watch-page layout, metadata, return link, transcript, and responsive presentation. | +| [Pro route](src/pages/videos/add-image-phoenix-pro.js) and [Community route](src/pages/videos/add-image-phoenix-community.js) | Separate `/videos/...` pages, one recording per page. | +| [tutorial-media-manifest.json](scripts/tutorial-media-manifest.json) | Capture provenance, project, measured duration, and any requested duration limit. | +| [verify-tutorials.cjs](scripts/verify-tutorials.cjs) | Checks the built tutorial pages, media, watch pages, and publication metadata. | + +These `Image...` components and data are specific to the image tutorial. For a +different topic, adapt or generalize the pattern with appropriate names and +verification coverage. Do not put unrelated recordings into the image registry. + +## Adding a recording and watch page + +1. Record the correct practice project, active file, and product edition. Show + the controls a new user should click, with short on-screen instructions and + highlights. Keep menus and properties fully visible. State any setup already + completed or system file-picker steps that are outside the recording. Keep + clips focused and honor the requested duration limit; the existing search + walkthroughs must remain under 30 seconds. +2. Save the MP4, representative poster image, and timed English `.vtt` captions + under `static/tutorials/media/`. Use stable filenames. Export the MP4 with + fast-start metadata and register it in `scripts/tutorial-media-manifest.json` + with its actual duration and capture details. Record verification only after + performing it. +3. Share one recording definition between its inline player and watch page. + Include the source, poster, captions, accessible label, descriptive name and + description, exact ISO 8601 duration (for example, `PT24S`), and actual recording + date in `dateCreated`. With the current verifier, write duration as `PT…S`. + Match the watch page's on-screen instructions to the caption cues; do not + invent spoken narration for a silent recording. +4. Add the `/videos/...` route using the existing Docusaurus layout. Give it a + unique page title and description, a representative social image, one player, + and one matching `VideoObject`. Reuse `TutorialVideo` rather than adding a + second hand-written schema. The article and watch page must describe the same + recording, poster, captions, duration, and publication date. +5. Add **Open video →** below the inline player and a return link to the matching + guide or edition. Confirm that the watch page has its own canonical URL and + appears in the generated sitemap, with no indexing or crawl block. +6. Extend `scripts/verify-tutorials.cjs` for the new article and watch route. Its + `GUIDES` list and image-watch-page checks are explicit; it does not + automatically discover every new video page. Keep verification code in + JavaScript and preserve the checks for shared metadata, links, captions, + publication dates, and a single visible watch-page player. + +## Preserve publication dates + +`dateCreated` records when the video was made. `uploadDate` is its first +publication date and is supplied by the media plugin during deployment. Adding +a watch page for an existing video must preserve that video's original date. +Do not hardcode `uploadDate`, replace it with the current build date, or invent a +date to make a check pass. + +Follow the [deployment notes](README.md#deployment). The workflow restores and +preserves `tutorials/video-publications.json`; local preview builds may leave +unpublished dates unset. Restore missing publication history before releasing. + +## Verify before and after release + +Run the [tutorial release checks](README.md#tutorial-release-checks). The build +includes local-link verification, and deployment additionally runs +`npm run verify:tutorials -- --release` against the build with publication dates. +Passing checks confirms the implementation, not Google's indexing decision. + +Preview the built article and watch page on desktop and mobile, in light and dark +themes. Check that the article still reads naturally, controls and captions are +not clipped, the video plays and seeks, keyboard navigation works, reduced motion +is respected, and the return link selects the correct edition. Also navigate +from the article to the watch page to catch stale metadata after client navigation. + +After deployment, check the live watch URL, MP4, poster, captions, and sitemap. +Use Search Console URL Inspection on the **watch page**: page indexing comes +before video indexing, and neither valid metadata nor a successful build +guarantees inclusion. The article's supplementary-video warning can remain; +preserve its reading layout while checking the watch page's result. diff --git a/README.md b/README.md index c3394c61b..1240c2514 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,10 @@ Run `npm run test:links` to test the checker. After a direct ### Tutorial release checks +Before adding or changing a video, read the +[video contributor notes](CONTRIBUTING.md#adding-or-updating-tutorial-videos) +for the recording, article, watch-page, and metadata workflow. + Run these checks before releasing tutorial changes. They use JavaScript and require Node.js, Git, and the dependencies installed by `npm ci`.