Skip to content
Merged

X #220

Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -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.
121 changes: 121 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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.
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down
28 changes: 3 additions & 25 deletions docs/10-Tutorials/01-add-images.md
Original file line number Diff line number Diff line change
Expand Up @@ -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**:

Expand Down Expand Up @@ -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.

<TutorialVideo
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',
}}
poster="/tutorials/media/pro-image-gallery.png" width="1360" height="980" style={{width: '100%', height: 'auto'}} aria-label="Phoenix Pro walkthrough: choose a photo from your device and set its description in first-website">
<source src="/tutorials/media/pro-add-image-complete.mp4" type="video/mp4" />
<track kind="captions" src="/tutorials/media/pro-add-image-complete.vtt" srcLang="en" label="English" />
<a href="/tutorials/media/pro-add-image-complete.mp4">Watch the Phoenix Pro walkthrough</a>.
</TutorialVideo>
<ImageTutorialVideo edition="pro" showWatchLink />

### Turn on visual editing

Expand Down Expand Up @@ -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.

<TutorialVideo
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',
}}
poster="/tutorials/media/community-select-image-tag.png" width="1360" height="980" style={{width: '100%', height: 'auto'}} aria-label="Community walkthrough: replace an image using Highlight Mode in first-website">
<source src="/tutorials/media/community-add-image.mp4" type="video/mp4" />
<track kind="captions" src="/tutorials/media/community-add-image.vtt" srcLang="en" label="English" />
<a href="/tutorials/media/community-add-image.mp4">Watch the Community walkthrough</a>.
</TutorialVideo>
<ImageTutorialVideo edition="community" showWatchLink />

### Find the picture's HTML

Expand Down
40 changes: 39 additions & 1 deletion scripts/verify-tutorials.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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);
Expand All @@ -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;
Expand All @@ -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');
Expand All @@ -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.');
}

Expand Down
30 changes: 30 additions & 0 deletions src/components/Video/ImageTutorialVideo.js
Original file line number Diff line number Diff line change
@@ -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 <><TutorialVideo
metadata={video.metadata}
poster={video.poster}
width="1360" height="980" style={{width: '100%', height: 'auto'}}
className={className} aria-label={video.label}>
<source src={video.source} type="video/mp4" />
<track kind="captions" src={video.captions} srcLang="en" label="English" />
<a href={video.source}>Watch the {edition === 'pro' ? 'Phoenix Pro' : 'Community'} walkthrough</a>.
</TutorialVideo>
{showWatchLink && <div className={styles.watchAction}>
<Link to={video.watchPath} aria-label={`Open video: ${video.title}`}>
Open video
<svg width="16" height="16" viewBox="0 0 24 24" fill="none"
stroke="currentColor" strokeWidth="1.75" strokeLinecap="round" strokeLinejoin="round"
aria-hidden="true" focusable="false">
<path d="M5 12h14m-6-6 6 6-6 6" />
</svg>
</Link>
</div>}
</>;
}
Loading
Loading