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`.
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
+
+
+ ;
+}
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 ;
+}