diff --git a/AGENTS.md b/AGENTS.md index 3cdf58e8..dec8786a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,12 @@ # Guidance for AI contributors +Before creating or revising documentation, read the +[documentation authoring guide](CONTRIBUTING.md#writing-and-updating-documentation). +It applies to tutorials, feature guides, troubleshooting, and blog articles. +Verify the real workflow, write complete steps for a beginner, and keep the +article, examples, screenshots, and recordings consistent. Correct an existing +guide when it already covers the task; create a new page for a distinct outcome. + 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). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 575212c0..6f55f5d7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,9 +1,14 @@ -# Contributing to Open Research -:+1::tada: Thanks for taking the time to contribute! :tada::+1: +# Contributing to Phoenix Code documentation + +Use this guide when writing, updating, or reviewing Phoenix Code documentation. +It applies to human contributors and AI agents. + ## Table of Contents + 1. [About the Project](#about-the-project) 1. [Project Status](#project-status) 1. [Getting Started](#getting-started) +1. [Writing and updating documentation](#writing-and-updating-documentation) 1. [Adding or updating tutorial videos](#adding-or-updating-tutorial-videos) ## Community engagement @@ -24,6 +29,256 @@ Documentation for phoenix/brackets # Getting Started * see https://github.com/phcode-dev/docs/blob/main/README.md +# Writing and updating documentation + +The goal is a page a new user can follow to a checked result. Use this workflow +for tutorials, feature guides, troubleshooting, and practical blog posts. Scale +it to the change: a wording correction does not need a new recording or practice +project. The [image tutorial](docs/10-Tutorials/01-add-images.md) and +[single-file replacement tutorial](docs/10-Tutorials/06-find-and-replace.md) show +the established structure and shared components. + +## Choose the reader's task and the right page + +- Start with a concrete outcome and the reader's starting point. Search queries, + support questions, and observed mistakes can reveal a gap; a model's answer + is not evidence that a product feature exists. Summarize private user examples + without publishing account details or conversation identifiers. +- Search existing guides before creating a page. Correct or extend the relevant + guide when the outcome is the same. Create a separate page when the scope or + workflow differs, then link related pages. Finding text across files and + replacing text in one file, for example, need different instructions. +- Keep established slugs and useful section anchors when revising a page. If a + heading changes, retain its old explicit ID where appropriate. Follow the + site's redirect conventions when a URL must change. +- Keep one main task per tutorial. Put prerequisites before the steps and + optional variants or troubleshooting after them. A short conceptual answer + does not need to become a tutorial. + +## Verify the workflow before writing it + +Perform the task in the real product with the intended project and file open. +Check the edition, platform, application version, and whether you are using the +desktop or web app. Record those details and the check date in the review notes. +Use a fresh practice copy when trying alternatives so earlier edits do not hide +missing steps or override later settings. + +- Check the complete path: open the project and file, select the right object, + enter the required mode, open the panel, change the value, apply it, save, and + inspect the result. Include dialogs that can appear along the way. +- Copy control names and locations from the actual interface. A command constant + or preference key in source code does not establish a visible menu or switch. + Check source code or official product documentation for behavior the interface + cannot show; distinguish that evidence from a workflow you ran yourself. +- State availability accurately. A free feature demonstrated while signed in + to Pro is not proof that the recording used a Community-only account. Verify + edition support before labeling the steps. +- For configuration, verify the file location, exact key and value, save/restart + requirements, scope, and limitations. For dependencies, cover the supported + operating systems or link directly to the installation steps. +- Inspect the saved file or exported output, not only the preview. Editing an + existing element should preserve unrelated attributes, classes, styles, and + content. Replacing a picture normally changes its `src` and `alt` values; + pasting a new whole tag can remove the reader's layout settings. +- If verification is incomplete, record the specific gap in the handoff. Do not + invent a control or present an untested procedure as verified. + +## Write complete steps in plain language + +Open with what the reader will accomplish, which editions it works in, and what +they need. Use familiar words and active verbs. Explain a technical term when +the reader first needs it, such as a project being the folder containing their +files. Remove promotional filler and vague claims; keep the details needed to +finish the task. A language review should improve clarity and accuracy, not +replace product verification with an AI-tone score. + +1. Tell the reader where to start. Name the project, active file, or selected + object where it matters. Offer a skip-ahead link when setup is already done. +2. Describe one action or a short sequence in each numbered step. Use the exact + control label and its location. Give a menu or visible-button route before + optional shortcuts, including platform differences where needed. +3. Say what changes after the action. A selected state, highlighted match, open + dialog, or changed preview helps the reader recognize the right screen. +4. For code, identify the file and insertion or edit location. Say whether to + insert new content or edit an existing value. Use a language-tagged code block + for code to copy, and explain each placeholder to replace. +5. Include applying and saving changes, the file affected, and a visible result + to check. For operations affecting several files or elements, explain the + scope before applying them and give only verified undo instructions. + +Prefer “Click the magnifying glass at the top left to open Find in Files” over +“Use the powerful search functionality.” A screenshot supports a step; it does +not replace an omitted instruction for reaching that screen. + +## Show editions, platforms, and practice files clearly + +When Pro and Community use different methods, show **Phoenix Pro first and by +default**, followed by **Community (free)**. Use the existing Docusaurus tabs: + +```jsx + +``` + +Import `Tabs` and `TabItem` as in the image tutorial, and use `pro` and `community` +as the tab values. Put descriptive headings inside each tab. Link to the relevant +edition and section using `?edition=community#section-id`, with the query before +the hash. Preserve a reader's explicit edition choice. See the +[Docusaurus tab documentation](https://docusaurus.io/docs/markdown-features/tabs#query-string). + +If both editions use the same steps, say so once and share the procedure. Label +platform differences where they affect the action instead of duplicating an +entire guide. Never describe a Pro-only control as available in Community. + +For Pro visual-editing tasks, show Design Mode when its larger preview helps. +Explain how to enter it and enable Edit Mode when needed. Community code-editing +tasks should show the editor beside Live Preview and explain Highlight Mode +where it locates the code. These are different modes; use their actual names. + +Add a practice project when it helps readers reproduce the task. Reuse a suitable +project in `static/tutorials/` before creating another. Explain extraction, Open +Folder, the file to open, and the starting result. Make a sample optional when +the task works equally well in the reader's own file. A new packaged project +also needs registration in [package-tutorials.cjs](scripts/package-tutorials.cjs) +and the relevant release verification. Keep its source, ZIP, written examples, +screenshots, and recordings in agreement. + +## Use recognizable icons and useful screenshots + +- Pair a control's shape with its written name and location. Reuse + [TutorialIcon](src/components/TutorialIcon/index.js), for example + ``. Use the actual + product icon, not an emoji substitute. Add new shapes and their attribution + to the shared icon map; follow the + [icon maintenance notes](config/search/README.md#small-control-icons-in-answers). +- Capture the real interface in the correct project, file, mode, and edition. + Do not generate or redraw product screenshots to imply a feature exists. + Remove private account data, credentials, and unrelated windows from the + capture setup. Use sample assets with a known license and keep attribution. +- Show the relevant control and enough surrounding interface to locate it. + Keep menus, property rows, values, and results fully visible. Scroll or enlarge + a panel before capture instead of publishing a clipped screenshot. +- Put each screenshot beside the step it explains. Write alternative text that + describes the relevant state or action. Use a stable public asset path and a + link to the full-size image when small details matter, as in the image tutorial. + Keep published assets available while older pages or answers still link to them. +- Check images at the article's display size on desktop and mobile, in light and + dark themes. Supply correct dimensions when writing raw `` markup. Use + one clear visual cue at a time; do not cover the control with an annotation. + +## Keep recordings consistent with the article + +Read the [video contributor notes](#adding-or-updating-tutorial-videos) before +changing any recording, player, metadata, or watch page. Use a recording when +motion helps explain the task. Aim for under 30 seconds for a new short task clip, +and honor any explicit duration limit; preserve understandable actions rather +than rushing to fit a target. For longer tasks, consider separate focused clips. + +Plan the actions, remove idle time, highlight the relevant control, and finish on +the actual saved result. State setup already completed outside the recording. +When a procedure changes, review its screenshots, recording, captions, poster, +and shared metadata together. Do not leave a video teaching the superseded steps. +Use a poster with the video's aspect ratio to avoid a size change on playback. + +Keep the complete written guide readable without playing a video. Reuse the +shared player and watch-page components, and follow the existing rules for +autoplay, reduced motion, captions, publication dates, and video discovery. + +## Structure pages for readers, search, and Ask AI + +Use descriptive titles and headings, an accurate description, stable URLs, and +useful links from related guides. In Docusaurus docs, front matter supplies the +page title; avoid adding a second H1. Set a relevant social image when one is +available. See the official +[front-matter reference](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter). +For blog posts, also follow the existing author, date, tag, and excerpt conventions, +including `` after a useful introduction. + +Use this outline when starting a tutorial. Replace all example values and +prompts with verified content; omit sections that do not serve the task. + +```md +--- +title: Complete a specific task +slug: /tutorials/task-name +description: Describe the outcome and method in one useful sentence. +toc_max_heading_level: 2 +--- + +Explain the outcome and which editions support it. + +**You'll need:** Name the required files, software, and starting state. + +## 1. Open the project or file + +Give the verified setup steps and expected starting screen. + +## 2. Make the change + +Give numbered actions, with edition tabs only when the methods differ. + +## 3. Save and check + +Name the save action and the result the reader should see. + +## Need help? + +Answer problems observed while following these steps. +``` + +- Make important steps, edition restrictions, and caveats available as text. + Group each instruction with its relevant heading and illustration so search + and Ask AI can retrieve a useful explanation. Keep full-size image links + crawlable; do not rely on a screenshot's text or a video alone. +- Add FAQs for real reader problems, with direct answers and concrete fixes. + Do not pad a page with repeated questions or keywords. Keep any structured + data consistent with visible content and reuse the site's existing mechanisms. +- Fix missing or incorrect information in the source guide. Do not add a recipe + for each question to the AI prompt. Readers may use a short request, a typo, + or a follow-up; sample varied wording when reviewing generated answers. +- Check the generated canonical URL, sitemap entry, and crawl/index permissions + for new public pages. Review generated `llms.txt` entries where applicable; + change the source or generator rather than hand-editing build output. +- Judge quality by accuracy, completeness, and whether a reader can succeed. + [Google's content guidance](https://developers.google.com/search/docs/fundamentals/creating-helpful-content) + emphasizes useful, reliable content for people. A style score, FAQ, video, + metadata field, or `llms.txt` file is not proof that Google has indexed a page. + +## Review, release, and hand off + +For published tutorial or blog changes, follow the +[tutorial release checks](README.md#tutorial-release-checks). Register new +tutorials, blog routes, and video registries in +[verify-tutorials.cjs](scripts/verify-tutorials.cjs) where applicable; it does not +automatically discover every new page. Use JavaScript for verification code. +Keep checks focused on meaningful behavior; prose edits do not need tests that +merely assert the new wording. For contributor-notes-only changes, review links +and the diff; a site build is unnecessary. + +Before release, follow the [dependency maintenance rules](AGENTS.md#package-upgrades-and-docsearch-maintenance). +Use the [search checks](README.md#search-and-ask-ai-checks) for search or Ask AI +changes. Keep shared tooling changes limited to what the documentation needs. + +Review the built page as a new reader. Follow the complete workflow from its +stated starting point, check every documented edition/platform variation, and +test links, downloads, code examples, screenshots, and saved results. Inspect +desktop and mobile layouts in light and dark themes. Check keyboard access and +the selected tab after opening an edition-specific link; follow the additional +visual checks for video pages. If a platform or behavior could not be checked, +state that limitation instead of marking the entire review complete. + +After deployment, check the live page and its assets. When indexed content has +changed, recrawl Algolia and test fresh answers against the new source, including +citations, screenshots, icons, and code formatting where relevant. Content-only +updates do not require republishing crawler settings or agent prompts. Use the +[search maintenance guide](config/search/README.md) when those settings also +change. Check Google indexing separately in Search Console; an Algolia crawl +does not request or confirm Google indexing. + +Leave a short handoff with the changed pages, product verification details, +checks actually run, remaining limitations, and commit or preview link. Distinguish +what is local, committed, deployed, recrawled, and confirmed indexed. Name the +next required action without claiming that an unperformed check passed. + # Adding or updating tutorial videos Use these notes when adding recordings, changing a video player, or creating a diff --git a/README.md b/README.md index 97339b4d..c3b16d5c 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,10 @@ This repository hosts the code for https://docs.phcode.dev/ . Please contribute to this repo for helping the Phoenix/Brackets community. +For contributors and AI agents, start with the +[documentation authoring guide](CONTRIBUTING.md#writing-and-updating-documentation). +It covers planning, product verification, writing, media, and release review. + ## License CC BY License Copyright (c) 2022-present, core.ai diff --git a/config/search/README.md b/config/search/README.md index 34ad63d7..f556da71 100644 --- a/config/search/README.md +++ b/config/search/README.md @@ -137,7 +137,7 @@ source guides so future documentation changes do not require prompt recipes. | --- | --- | | `how to add image` and `how to add ima` | Pro first: open the HTML page and Live Preview, enable Edit Mode, insert and select the new image, choose it through Image Gallery / Select from device, handle the folder prompt, add a description, save, and check the result. Community: the image-folder location, where to insert a complete HTML example, exact filename and description, saving, and preview. Each edition should include a relevant source screenshot and a full-size link. | | `add images` and `add imagfes` | The same complete, illustrated add-image walkthrough. Do not require a question, the words "how to", corrected spelling, or an explicit request for screenshots. | -| `how do I replace a picture in Community?` | Community-only steps, Highlight Mode to locate the existing tag, selection or editing of that tag without adding a duplicate, and a saved result. | +| `how do I replace a picture in Community?` | Community-only steps, Highlight Mode to locate the existing tag, editing only its `src` and `alt` values while preserving styling and other attributes, and a saved result without a duplicate image. | | `replace image community` | The same Community-only replacement workflow, with a relevant Community screenshot. Do not treat the short wording as permission to omit steps or claim that the assistant has edited the user's project. | | `find and replace` | The current-file walkthrough, opening Replace, entering both values, reviewing/replacing matches, and saving. Distinguish project-wide replacement without forcing both procedures into one answer. | | `What does alt mean?` | A short explanation of the image description, with a small example if useful. Do not repeat the full image tutorial. | @@ -494,8 +494,9 @@ Prompt changes alone cannot restore an icon absent from the retrieved source. preference; a pending update and some checks can precede that preference gate. Added the precise desktop preference workflow and limitations to [Managing App Updates](../../docs/09-Schools%20%26%20Workplaces/03-managed-updates.md). - This guide change is local and still needs website deployment and a recrawl. - Do not claim that the live assistant can already retrieve its new instructions. + This guide was subsequently deployed and recrawled. The 19 November checks + confirmed the live page includes the preference workflow and limitations, + and the model comparison retrieved those instructions successfully. - Published and read back the new extraction actions and `initialIndexSettings`. The completed crawl had 252 successful URLs, 43 ignored URLs, and no failures; it retained 5,449 keyword records and 203 AI records. All 116 API records carry @@ -524,9 +525,9 @@ Prompt changes alone cannot restore an icon absent from the retrieved source. instructions instead link adjacent material without substituting its steps. - These are sampled improvements, not a guarantee of concise or error-free answers. Some responses still include extra explanation and repeated searches. - The current auto-update response acknowledges the missing end-user procedure; - retest it after deploying and crawling the new guide. Record visible answer - outcomes without saving raw diagnostic request/response traffic that may + The auto-update response at this checkpoint acknowledged a missing end-user + procedure; the later deployment and retrieval checks above resolved that gap. + Record visible answer outcomes without saving raw diagnostic request/response traffic that may include private configuration. - A fresh answer on the deployed search page retained the Pro and Community insertion workflows, two loaded screenshots, six source-backed control icons @@ -544,6 +545,74 @@ Prompt changes alone cannot restore an icon absent from the retrieved source. warnings remain. The new preference instructions were reviewed at desktop and 390 px widths with no horizontal overflow. +### Model comparison and rollback on 19 November 2026 + +- At the owner's request, temporarily changed the published documentation + agent's model from `anthropic/claude-sonnet-5.5` to `openai/gpt-6.1-terra`, + then restored **`anthropic/claude-sonnet-5.5`** when the owner requested a + rollback later the same day. Both changes were saved in Agent Studio and + verified after reloading. The existing `Phoenix Docs Sonnet Production` + OpenRouter connection, prompts, tools, indices, credentials, and billing + settings were retained. +- Before the switch, Terra completed six comparison questions, averaging + 17.5 seconds and costing approximately $0.100 in OpenRouter charges. The + comparison included image insertion, a follow-up, Community replacement, + project replacement, update preferences, and an undocumented sync feature. + These are small-sample results, not a quality or latency guarantee; some + answers still omitted access steps or the large-project undo caveat. +- While Terra was active, a fresh public-site image question completed with Pro + and Community steps, two loaded screenshots, seven loaded control icons, highlighted HTML, and + no horizontal overflow in the desktop answer panel. OpenRouter's visible + generation logs confirmed `GPT-6.1 Terra` through its OpenAI provider. +- After restoring Sonnet, a fresh public Community replacement answer completed + with a loaded screenshot, control icon, and highlighted HTML. OpenRouter logs + confirmed `Claude Sonnet 5.5` for that public request. The answer recommended + whole-tag replacement and mentioned restoring dimensions, but did not explain + preserving other attributes; this check confirms operation, not error-free + guidance. Continue reviewing source completeness when sampling answers. +- Change models through the same published agent's Model field, save, reload, + and verify a fresh public answer. Do not create another agent or provider. + These changes take effect without a website deployment or recrawl. +- Checked the live npm registry and official + [DocSearch changelog](https://github.com/algolia/docsearch/blob/main/packages/docsearch-react/CHANGELOG.md) + and [Docusaurus release notes](https://github.com/meta/docusaurus/releases/tag/v3.10.2). + The latest stable versions remain DocSearch `5.2.0` and Docusaurus `3.10.2`. + The manifest, lockfile, and vendored `5.2.0-phcode.2` build agree with those + upstream versions; no dependency upgrade was needed. This was a hosted + model change and notes-only repository edit, so no website rebuild was needed + for the model rollback itself. + +### Community image replacement correction on 19 November 2026 + +- Updated the existing [Add an image tutorial](../../docs/10-Tutorials/01-add-images.md) + to change only the existing image's `src` path and `alt` description. Keep + `class`, `id`, `style`, dimensions, and other attributes instead of replacing + the whole tag. The FAQ also covers relative paths and images selected through + `srcset` or ``. No new tutorial or topic-specific agent rule was added. +- Re-recorded the Community walkthrough in the unchanged `first-website` + practice project. The saved file differs only in its image path and description; + Live Preview contains one loaded photo and retains `width="960" height="480"`. + The 28-second recording, screenshots, captions, and shared watch-page metadata + now show the same procedure. Its poster matches the video's dimensions. +- Kept the article, replacement-section anchor, watch page, and MP4 URLs. + Restored the original publication manifest from `gh-pages`; the existing + Community video's `uploadDate` remains `2026-11-10T08:40:33.985Z`. Its + `dateCreated` records the new capture. Retained the older screenshot file so + links in previously generated answers do not become missing assets. +- Passed the tutorial and search tests, practice-project packaging, production + build using the current generated API files, local-link and search checks, + and `verify:tutorials -- --release` with restored publication dates. Existing + blog truncation and unrelated blog/API anchor warnings remain. Reviewed the + article and watch page at 1440 px and 390 px in light and dark themes; checked + normal-speed playback, seeking, timed captions, keyboard controls, offscreen + pause, reader-pause preservation, reduced motion, and the Community return + link. The updated pages have no horizontal overflow or application exceptions. +- This correction still needs website deployment, an Algolia recrawl, and a + fresh public Ask AI check. Test both `replace image community` and a question + about replacing a picture without losing its styling. Check the retrieved + instructions and screenshots as well as the answer; do not assume deployment + alone refreshes the index. The published Sonnet agent remains unchanged. + ## Official references - [Docusaurus query-string tabs](https://docusaurus.io/docs/markdown-features/tabs#query-string) diff --git a/docs/10-Tutorials/01-add-images.md b/docs/10-Tutorials/01-add-images.md index 085eba03..13023516 100644 --- a/docs/10-Tutorials/01-add-images.md +++ b/docs/10-Tutorials/01-add-images.md @@ -112,7 +112,7 @@ For the steps below, we'll use the name `photo.jpg`. If your file is named `holi ### Watch the Community steps -This 31-second recording starts with `photo.jpg` already copied into the project's `images` folder. +This 28-second recording starts with `photo.jpg` already copied into the project's `images` folder. @@ -128,29 +128,34 @@ Keep the code editor and Live Preview side by side. If the preview fills the app [![Highlight Mode selected in the practice project's Live Preview mode menu](/tutorials/media/community-highlight-menu.png)](/tutorials/media/community-highlight-menu.png) -### Replace the picture's HTML +### Change the picture's file and description {#replace-the-pictures-html} -Clicking the preview places the cursor at the tag. Select that tag before pasting so you replace the existing picture. +Highlight Mode places the cursor at the existing `` tag. Edit the values +inside that tag to replace the picture while keeping its styling and position. -1. In the code editor, drag to select the whole tag, from ``. +1. Find `src`, which tells the page which picture to load. Select only the path + **between its quotation marks**. In the practice project, select + `images/trail.svg` and type `images/photo.jpg` in its place. Keep the quotation marks. -[![The whole img tag selected in the code editor, with the matching picture highlighted in Live Preview](/tutorials/media/community-select-image-tag.png)](/tutorials/media/community-select-image-tag.png) +[![Only the image path selected inside src, with the rest of the img tag and its width and height left intact](/tutorials/media/community-edit-image-source.png)](/tutorials/media/community-edit-image-source.png) -The blue selection in the editor shows the code to replace. It can wrap onto several screen lines and still be one `` tag. - -2. Paste this in its place: - -```html -Describe your photo here -``` - -3. Change `photo.jpg` to your picture's exact filename. -4. Replace `Describe your photo here` with a short description, such as `My dog playing in the park`. +2. Use your picture's exact filename and extension. For example, a file named + `holiday.png` in the same folder needs `src="images/holiday.png"`. +3. Find `alt` in the same tag. Replace only the description between its quotation + marks. For the sample photo, use `Sunlit forest path`. This description helps + people using screen readers understand the picture. +4. Leave the rest of the tag in place, including any `class`, `id`, `style`, + `width`, and `height` attributes. These may control the picture's appearance + or connect it to the rest of your page. There is no need to paste a new + `` tag or add another image. 5. Save with **Ctrl+S** or **Cmd+S**. +If your image has no `alt`, add `alt="Your description"` inside its existing +`` tag, with a space before the attribute. Keep the closing `>`. + **You should see your photo replace the hills in Live Preview.** The practice website already makes pictures fit the page. -[![The sample forest-path photo replacing the hills, with images/photo.jpg in the HTML](/tutorials/media/community-image-result.png)](/tutorials/media/community-image-result.png) +[![The forest-path photo in Live Preview, with the new src and alt values and the original width and height in the HTML](/tutorials/media/community-image-result.png)](/tutorials/media/community-image-result.png) @@ -172,7 +177,7 @@ The finished page above is shown in Design Mode. To check it inside Phoenix Code
Can I add images with the free Community edition? -Yes. Community includes **Highlight Mode**, which lets you click a picture in Live Preview to find its HTML. Select the whole `` tag, replace the filename and description, and save. Follow the [Community steps](/docs/tutorials/add-images?edition=community#copy-your-picture) above. +Yes. Community includes **Highlight Mode**, which lets you click a picture in Live Preview to find its HTML. Change the `src` path and `alt` description in the existing `` tag, keep its other attributes, and save. Follow the [Community steps](/docs/tutorials/add-images?edition=community#copy-your-picture) above.
@@ -190,6 +195,11 @@ You can also find this picture with **Ctrl+F** on Windows/Linux or **Cmd+F** on Check that your picture is inside `first-website/images`. Then compare its filename with the name after `images/` in the HTML. The spelling, capital letters, and extension must match. `photo.jpg` and `photo.jpeg` are different filenames. +On your own website, the path is relative to the HTML file's folder. If the image +also has `srcset`, or sits inside a `` element with `` entries, +the browser may choose one of those image files instead. Update the relevant +image paths there too; keep the attributes that control your layout. + In Pro, select the picture and choose **Image Gallery > Select from device** again to set its file automatically. diff --git a/scripts/tutorial-media-manifest.json b/scripts/tutorial-media-manifest.json index 162c71c0..14bc8488 100644 --- a/scripts/tutorial-media-manifest.json +++ b/scripts/tutorial-media-manifest.json @@ -23,15 +23,26 @@ { "file": "static/tutorials/media/community-add-image.mp4", "project": "first-website", - "workflow": "Highlight Mode, select and replace img tag, save", + "workflow": "Choose Highlight Mode, click the existing picture, select only its src path and replace it, update only the alt description, save, and check the replacement while keeping the other attributes.", "on_screen_instructions": true, "system_file_picker_recorded": false, - "duration_seconds": 31.16, + "duration_seconds": 28, "frame_size": [ - 1360, - 980 + 1280, + 844 ], - "caption_placement": "Above the screen recording, clear of player controls" + "caption_placement": "Above the screen recording, clear of player controls", + "captured_at": "2026-11-18T19:27:57.585Z", + "duration_limit_seconds": 30, + "highlighted_controls": true, + "presentation": "Actual Phoenix Code pointer and keyboard actions in the first-website practice project, using free Community features. The full recording is slowed uniformly to 28 seconds for readable instructions.", + "verification": [ + "Project root is first-website and the active file is index.html", + "Clicking the existing picture in Highlight Mode places the cursor on its img tag", + "The saved file matches the original exactly except for images/trail.svg becoming images/photo.jpg and the alt description becoming Sunlit forest path", + "index.html is no longer dirty after saving with Ctrl+S", + "Live Preview loads one image with src images/photo.jpg and alt Sunlit forest path; width 960 and height 480 are unchanged" + ] }, { "file": "static/tutorials/media/pro-add-image-complete.mp4", diff --git a/src/data/image-tutorial-videos.json b/src/data/image-tutorial-videos.json index c3c2f792..f9bc4663 100644 --- a/src/data/image-tutorial-videos.json +++ b/src/data/image-tutorial-videos.json @@ -34,21 +34,24 @@ "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", + "width": 1280, + "height": 844, + "poster": "/tutorials/media/community-add-image-poster.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" + "description": "Replace the picture in the first-website practice project using free Community features. Use Highlight Mode to find its existing img tag, change only the src path and alt description, keep the other attributes, and save.", + "duration": "PT28S", + "dateCreated": "2026-11-19" }, "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." + "Community: choose Highlight Mode beside the pen.", + "Click the picture to find its existing image tag.", + "Change only the src path to images/photo.jpg.", + "Update the alt description. Keep the other attributes.", + "Save with Ctrl+S on Windows/Linux or Cmd+S on Mac.", + "Check your photo. Width and height are unchanged." ] } } diff --git a/static/tutorials/media/community-add-image-poster.png b/static/tutorials/media/community-add-image-poster.png new file mode 100644 index 00000000..8784903e Binary files /dev/null and b/static/tutorials/media/community-add-image-poster.png differ diff --git a/static/tutorials/media/community-add-image.mp4 b/static/tutorials/media/community-add-image.mp4 index 0ab0f548..cb138ad5 100644 Binary files a/static/tutorials/media/community-add-image.mp4 and b/static/tutorials/media/community-add-image.mp4 differ diff --git a/static/tutorials/media/community-add-image.vtt b/static/tutorials/media/community-add-image.vtt index 1b98434c..5af63a67 100644 --- a/static/tutorials/media/community-add-image.vtt +++ b/static/tutorials/media/community-add-image.vtt @@ -1,16 +1,19 @@ WEBVTT -00:00:00.000 --> 00:00:04.050 -Community: choose Highlight Mode from the arrow beside the pen. +00:00:00.000 --> 00:00:02.978 +Community: choose Highlight Mode beside the pen. -00:00:04.050 --> 00:00:09.465 -Click the hills in Live Preview. The editor finds the image tag. +00:00:02.978 --> 00:00:05.548 +Click the picture to find its existing image tag. -00:00:09.465 --> 00:00:18.417 -In the editor, select the whole image tag before replacing it. +00:00:05.548 --> 00:00:12.651 +Change only the src path to images/photo.jpg. -00:00:18.417 --> 00:00:23.127 -Paste the new tag. Use your picture filename and a short description. +00:00:12.651 --> 00:00:22.848 +Update the alt description. Keep the other attributes. -00:00:23.127 --> 00:00:30.765 -Save with Ctrl+S (Windows/Linux) or Cmd+S (Mac). Your photo is in the page. +00:00:22.848 --> 00:00:25.109 +Save with Ctrl+S on Windows/Linux or Cmd+S on Mac. + +00:00:25.109 --> 00:00:28.000 +Check your photo. Width and height are unchanged. diff --git a/static/tutorials/media/community-edit-image-source.png b/static/tutorials/media/community-edit-image-source.png new file mode 100644 index 00000000..c8700516 Binary files /dev/null and b/static/tutorials/media/community-edit-image-source.png differ diff --git a/static/tutorials/media/community-image-result.png b/static/tutorials/media/community-image-result.png index d581c3d8..a038f3a6 100644 Binary files a/static/tutorials/media/community-image-result.png and b/static/tutorials/media/community-image-result.png differ