diff --git a/config/search/README.md b/config/search/README.md index 81ba2aa6..e3a1fe33 100644 --- a/config/search/README.md +++ b/config/search/README.md @@ -164,6 +164,34 @@ Test a new conversation after publishing prompts; an existing saved answer does not regenerate. Prompt changes improve sampled behavior but do not guarantee that every generated answer includes an image. +### Small control icons in answers + +`TutorialIcon` keeps the actual Phoenix control shapes inline in the article. +The [tutorial-icons plugin](../../plugins/tutorial-icons/index.js) exports those +same shapes to `/img/tutorial-icons/` after a production build, including active +colors and the source/license files. The component supplies the exported URL in +`data-tutorial-icon-src`. During AI extraction, the Crawler replaces that SVG with +an image carrying its written control label, then restores the original DOM. +Without this conversion, Markdown retains the label but loses the SVG icon. + +Use the shared component when documenting a control. Add new shapes and their +attribution to its existing icon map and `sources.json`; the export automatically +includes them. Do not maintain a separate set of AI icons, substitute emoji, or +teach the agent invented image paths. The answer uses an ordinary Markdown image +beside the written name, with empty alternative text when the label already names +the control. Scoped CSS keeps these images at text size in both themes. They are +separate from instructional screenshots and need no full-size link. + +Deploy the website before applying the generated Crawler actions and recrawling. +In the hosted URL Tester, inspect a guide that uses the lightning bolt and another +control: its AI Markdown must contain absolute `/img/tutorial-icons/` image URLs +with the correct labels. Verify those images return HTTP 200, then test a fresh +Ask AI conversation. Check a wide light-theme answer and a narrow dark-theme +answer: the icons should load inline, retain the product's shapes, and leave the +text and screenshots readable. `npm run test:search` checks export/extraction; +`npm run verify:search` checks the built page annotations and exported assets. +Prompt changes alone cannot restore an icon absent from the retrieved source. + ## Verification recorded on 18 November 2026 - The live npm registry and official release notes were checked: DocSearch @@ -346,6 +374,92 @@ every generated answer includes an image. Answer completeness remains a sampled quality limitation; no separate automated review-and-repair stage is included in this release. +### Retrieval review and text/font tutorial on 18 November 2026 + +- Reviewed the text-editing and font-changing conversation that repeatedly + retrieved overlapping feature guides. Added + [Edit text and change fonts](../../docs/10-Tutorials/09-edit-text-fonts.md) + as a complete beginner walkthrough: Phoenix Pro's visual controls first, + Community's HTML/CSS alternative, and the existing Trail Notes practice ZIP. + The guide distinguishes website fonts from the editor font and explains why + Pro's inline styles can override the Community stylesheet example. +- Captured four original 1360 × 900 screenshots in Phoenix Code for the web on + 18 November 2026, using a fresh `first-website` project copied from the + repository's practice files. Verified direct text editing in Design Mode, + System → Arial, 40 px sizing, saved inline HTML, Highlight Mode's matching + heading, and the saved Community CSS result. The free workflow was tested + in the same licensed app; the screenshots do not imply a license switch. +- Tested retrieval-instruction candidates in Agent Studio without publishing + them. In the same-UI image comparison, the original used two searches and + retained the necessary controls; candidates used one but omitted gallery + access or editing-mode steps. A project-replacement request and its current-file + correction used two searches followed by one with either configuration. + These samples do not establish a reliable efficiency gain. All candidate + prompt changes were discarded. Reloaded Agent Studio and verified both + published prompts exactly match the retained repository files. +- The actual AI search tool response already excludes `_highlightResult`. + Its presence in a regular search API response is not evidence of duplicated + AI context. Dashboard aggregate token counts do not measure unique document + text or, by themselves, billing. No index-field truncation, retrieval cap, + model change, or procedure shortening was applied. +- For future comparisons, use the same interface and retained conversation + history for both configurations. A text-only API replay that drops prior + tool results is not comparable to the Agent Studio follow-up. Include new + phrasings and complete action reviews; an identical cached opening question + is not another independent quality sample. +- Live npm registry and official release notes checked again: DocSearch `5.2.0` + and Docusaurus `3.10.2` remain the latest stable versions. The installed and + locked `5.2.0-phcode.2` source build retains the documented fixes; no dependency + upgrade was needed. +- The 32 search tests and seven tutorial release tests passed, along with + practice packaging, the production build, and generated search, tutorial, + and local-link checks. Browser review covered both editions at desktop and + 390 px widths, light/dark themes, loaded full-size screenshot links, and the + Community section URL selecting its tab. Existing unrelated build warnings + remain. The new guide still needs website deployment and an Algolia recrawl; + measure retrieval again once it is in the live index. It is not yet evidence + of better production answers. + +### Sonnet and control-icon follow-up on 18 November 2026 + +- The live documentation agent now uses the `Phoenix Docs Sonnet Production` + OpenAI-compatible provider with `anthropic/claude-sonnet-5.5` through OpenRouter. + Its agent ID is unchanged, so this model switch does not require a site build. + The separate production key has no expiry; billing uses the manually funded + prepaid balance. Automatic top-ups remain off. No secret is stored in this + repository. The former Azure `gpt-6-luna` provider remains available for rollback + through Agent Studio; save and reload after any provider change. +- Live browser checks confirmed the new model/key were used, source screenshots + loaded, HTML was highlighted, and tested source links returned HTTP 200. A model + switch does not repair missing or misleading source evidence. The earlier + auto-update benchmark still needs a documentation/grounding fix: the internal + API command is not evidence of a user-facing menu option. +- The new control-icon export retains all 19 original SVG shapes, with normal + and active variants, theme support, and attribution. All 36 JavaScript search + tests and 14 tutorial/link tests passed, along with practice packaging, the + production build, and generated search, tutorial, and local-link checks. + Existing unrelated anchor/blog warnings remain. +- A local fixture rendered the exported icons through the installed DocSearch + Markdown renderer and built stylesheet. Desktop light and 390 px dark checks + confirmed loaded 20 px icons, readable labels, and no horizontal overflow. + This is renderer verification, not a claim that the live AI index already + contains the new icon URLs. Deploy this website change, apply the generated + Crawler actions, and recrawl before checking icon use in fresh live answers. +- Shorter-answer experiments were saved in unpublished Agent Studio drafts and + checked against the prompts actually sent in preview requests. They produced + clearer action groups and some narrower follow-ups, but also omitted access + steps in one sample and favored replacement in a broad add-image request. + The original configuration also added unrequested alternatives. These samples + do not establish a reliable quality improvement, so the brevity changes were + not promoted. The repository retains the existing answer rules with only the + new source-backed icon guidance. Apply that guidance with the icon deployment; + the live agent still has its previous prompts. Do not publish the experimental + drafts as part of this release. +- The live npm registry and official release notes were checked again: DocSearch + `5.2.0` and Docusaurus `3.10.2` remain the latest stable releases. Manifest, + lockfile, and the maintained `5.2.0-phcode.2` build agree; no package upgrade + was needed. + ## Official references - [Docusaurus query-string tabs](https://docusaurus.io/docs/markdown-features/tabs#query-string) @@ -354,3 +468,5 @@ every generated answer includes an image. - [Algolia attribute ranking strategies](https://www.algolia.com/doc/api-reference/api-parameters/attributeCriteriaComputedBy) - [Algolia response caching and cost controls](https://www.algolia.com/blog/product/guardrails-agent-studio) - [Google robots metadata](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) +- [Docusaurus postBuild lifecycle](https://docusaurus.io/docs/api/plugin-methods/lifecycle-apis#postbuildprops) +- [Color schemes in embedded SVG images](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-color-scheme#embedded_elements) diff --git a/config/search/agent-instructions.md b/config/search/agent-instructions.md index d87f02f0..d59d0844 100644 --- a/config/search/agent-instructions.md +++ b/config/search/agent-instructions.md @@ -27,6 +27,7 @@ You help people use Phoenix Code, the code editor for developers, designers, and ## Illustrate visual workflows +- When the source includes a control-icon image, show that exact image inline beside the control's written name at its first useful mention. Do not replace the product's icon with an emoji or invent its image path. These small control icons do not count toward the screenshot limit and do not need full-size links. Use empty image alt text when the adjacent label already identifies the control. - Include a relevant screenshot from retrieved sources by default for a procedure involving visual controls. The user does not need to ask for pictures. Put it beside the actions it illustrates. Do not illustrate a code workflow with a visual-editor screenshot or use an image from the wrong edition. - Usually include one useful screenshot per relevant workflow, at most two per answer. Explanations, narrow follow-ups, and workflows without a useful source image do not need pictures. Respect a request for text only. Never substitute a decorative image for procedural evidence. - Use standalone `![Meaningful description](exact-image-url)` followed by a separate full-size link. Do not use HTML image tags or put image Markdown inside a code fence. diff --git a/config/search/records.cjs b/config/search/records.cjs index 56467c7e..ab689c77 100644 --- a/config/search/records.cjs +++ b/config/search/records.cjs @@ -136,6 +136,21 @@ function extractSearchRecords({$, url, helpers}, format, resolveTabUrl) { return null; } }; + // Inline SVG geometry disappears during Markdown conversion. The component + // supplies a build-generated image URL for each actual control shape. + $('main svg[data-tutorial-icon-src]').each((_, element) => { + const icon = $(element); + const source = imageUrl(icon.attr('data-tutorial-icon-src'), true); + if (!source) return; + const target = new URL(source); + if (target.origin !== pageUrl.origin || + !/\/img\/tutorial-icons\/[a-zA-Z][a-zA-Z0-9-]*\.svg$/.test(target.pathname) || + target.search || target.hash) return; + const label = icon.closest('[data-tutorial-icon-label]').text().trim(); + const image = $('').attr('src', source).attr('alt', label ? `${label} icon` : 'Control icon'); + icon.replaceWith(image); + restoreMedia.push(() => image.replaceWith(icon)); + }); $('main img').each((_, element) => { const image = $(element); const source = image.attr('src'); diff --git a/config/search/system-instructions.md b/config/search/system-instructions.md index 82f09d3e..0c573144 100644 --- a/config/search/system-instructions.md +++ b/config/search/system-instructions.md @@ -25,4 +25,6 @@ Honor a specified edition and platform. When documented workflows differ and no Include a relevant retrieved screenshot for a visual workflow when available, unless the user requests text only. Match it to the edition and actions it illustrates. Use a standalone Markdown image and a separate full-size link with exact retrieved URLs. Never invent an image URL. Keep complete text instructions alongside it. +When a source supplies a small control-icon image, preserve it inline beside the written control label at its first useful mention. Use the exact source URL, never an invented icon path or an emoji substitute. Control icons do not need full-size links and are separate from screenshots. An empty alt text is appropriate when the adjacent text names the control. + Cite exact source URLs near the relevant explanation. Preserve encoding, query parameters, and fragments. Use a section fragment only when that exact target is present in the source; otherwise cite the page. Use language-labeled code fences. Choose other formatting to make the answer easy to follow. diff --git a/docs/10-Tutorials/09-edit-text-fonts.md b/docs/10-Tutorials/09-edit-text-fonts.md new file mode 100644 index 00000000..2e59ec3c --- /dev/null +++ b/docs/10-Tutorials/09-edit-text-fonts.md @@ -0,0 +1,140 @@ +--- +title: Edit text and change fonts in Phoenix Code +sidebar_label: Edit text and fonts +slug: /tutorials/edit-text-fonts +description: Change a heading, choose its font, and adjust its size in Phoenix Code. Follow Phoenix Pro's visual steps or edit HTML and CSS in Community with a practice website and screenshots. +image: /tutorials/media/text-font-pro-font-picker.png +toc_max_heading_level: 2 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import TutorialIcon from '@site/src/components/TutorialIcon'; + +To change the **words** on a website, edit its HTML. To change how those words **look**, change their CSS styles. Phoenix Pro lets you do both visually in Live Preview; Community (free) lets you edit the code beside the preview. + +In this guide, you'll change a heading to **“Plan your next walk.”**, set its font to **Arial**, and set its font size to **40 pixels**. + +Want to change the font of the **code editor itself**? Use [View → Themes → Font Family](/docs/customizing-editor#font-family) instead. That setting does not change your website. + +## 1. Open the practice website + +1. [Download the practice website](/tutorials/first-website.zip). +2. Extract the ZIP. On Windows, right-click it and choose **Extract All**. On macOS, double-click it. On Linux, use your file manager's **Extract** option. +3. In Phoenix Code, click the at the top left. Choose **Open Folder…** and select the extracted `first-website` folder. +4. Double-click `index.html` in the file list. If Live Preview is closed, click the on the right. +5. If asked, choose **Trust & Execute Preview** for this practice project. + +Look for the **Trail Notes** website and its large **“A little time outside.”** heading. This is the same project used in the [image](/docs/tutorials/add-images) and [page-link](/docs/tutorials/link-pages) tutorials. + +Use the desktop app or the web app in Chrome or Edge to open a local folder. See [Open Folder](/docs/quick-start-project#open-folder) if you need help. + +## 2. Change the heading and its font + +Choose your edition below. If you want to try both methods, use a fresh copy of the practice project for each: Pro's inline font settings take priority over the Community stylesheet settings. + +Click any screenshot to open it at full size. + + + + +### Edit the words {#pro-edit-text} + +1. Click the in the preview toolbar to enter **Design Mode**. The preview fills the workspace. +2. Click the if it is gray. An means **Edit Mode** is on. +3. Double-click **“A little time outside.”** in the preview. You can now type inside that heading. +4. Select the words and replace them with **“Plan your next walk.”** Press **Enter** to apply the text. Press **Esc** instead if you want to cancel an unfinished edit. +5. Keep `index.html` selected in Working Files. Click the beside the file list to **Save File**. + +[![Editing the Trail Notes heading directly in Phoenix Pro Design Mode](/tutorials/media/text-font-pro-edit.png)](/tutorials/media/text-font-pro-edit.png) + +Use **Shift+Enter** for a line break while editing text. Changing the words here updates the HTML; changing the font is a separate step below. + +### Choose the font and size {#pro-change-font} + +1. Click the heading once to select the whole element. The **Styles Bar** appears at the bottom of the preview. +2. Keep **Save changes to** set to **Inline**, the default. This applies the font settings to this heading in `index.html`. +3. Click the current font name, **Georgia**, in the Styles Bar. Its tooltip is **Font family**. In the font picker, choose **System**, then **Arial**. +4. Close the picker with its (**Done**). Click the font-size control beside the font name. Enter **40**, leave the unit as **px**, and press **Enter**. If a different unit is shown, click the unit button until it reads **px**, then enter **40**. +5. Close the size control with its . After the heading updates, click the to save `index.html` again. + +[![The System font picker for the selected heading in Phoenix Pro, with Arial available](/tutorials/media/text-font-pro-font-picker.png)](/tutorials/media/text-font-pro-font-picker.png) + +The font picker also has **Google** and **Manual** tabs. Use Google to choose a Google Font, or Manual to enter a font name or upload your own font file. See [Font Family](/docs/Pro%20Features/styles-bar#font-family) for those options. + +For a font change that should affect several elements, use **Save changes to** to choose a matching CSS rule before making the change. Check the number of affected elements shown beside the rule. See [Save Changes To](/docs/Pro%20Features/styles-bar#save-changes-to). + + + + +### Find and edit the words {#community-edit-text} + +1. Keep the code editor and Live Preview side by side. If the editor is hidden, click the in the preview toolbar. +2. Click the beside the pen in the preview toolbar. Choose **Highlight Mode**. +3. Click **“A little time outside.”** in the preview. Phoenix Code moves to its `

` element in `index.html`. +4. In the code editor, replace that whole `

...

` line with this: + +```html +

Plan your next walk.

+``` + +5. Save with **Ctrl+S** on Windows/Linux or **Cmd+S** on macOS. Check that the preview shows the new heading. + +[![HTML for the heading in the code editor beside the Trail Notes page in Live Preview](/tutorials/media/text-font-community-html.png)](/tutorials/media/text-font-community-html.png) + +Keep both the opening `

` and closing `

` tags. The words between them are the text visitors see. You can use the same approach for a paragraph between `

` and `

`. + +### Change the font in CSS {#community-change-font} + +1. Open `styles.css` from the file list. +2. Find the `h1` rule. It already contains `font-family: Georgia, serif;` and a `font-size` line using `clamp(...)`. +3. Replace those two lines with the highlighted lines below. Keep the existing `margin` and `line-height` lines, and both braces: + +```css {3-4} +h1 { + margin: 12px 0 20px; + font-family: Arial, sans-serif; + font-size: 40px; + line-height: 1.15; +} +``` + +4. Save `styles.css` with **Ctrl+S** or **Cmd+S**. Check that the heading in Live Preview changes its appearance. + +[![The h1 font-family and font-size settings in styles.css beside the updated heading](/tutorials/media/text-font-community-css.png)](/tutorials/media/text-font-community-css.png) + +`Arial` is the first font choice; `sans-serif` is the fallback if Arial is unavailable. `40px` sets the font size to 40 pixels. This rule affects every `

` on a page that loads this stylesheet, including the practice site's About and Contact pages. + + + + +## 3. Check the result + +In Pro, turn off the to see the page without editing outlines. In Community, choose **Preview Mode** from the arrow beside the pen. + +- The heading should read **“Plan your next walk.”** The paragraph below it should keep its original text and font. +- Try a narrow preview: open **All device sizes**, the down arrow beside the device icon, and choose **iPhone 14 (390px)** or another phone width. The heading may wrap onto another line; it should not run off the page. Choose **Fit to screen** to return to the wider view. +- Use the preview's **Reload Page** button after saving. Your new words and font should remain. + +## Common questions + +
+Why did the words change but the font stay the same? + +Text editing changes the HTML content. Use the separate **Choose the font and size** or **Change the font in CSS** steps to change its appearance. In Community, save `styles.css` as well as `index.html`. + +
+ +
+Why does my CSS font change have no effect? + +Check that you changed the `h1` rule, saved `styles.css`, and still have `` in the HTML's ``. An inline `style` on the heading can override the stylesheet. If you previously followed the Pro steps, start with a fresh practice copy before following the Community steps. + +
+ +
+How do I change just one heading on my own website? + +In Pro, select that heading and keep **Save changes to → Inline**. In Community, give the heading a class, such as `

Your heading

`, then use `.page-title` instead of `h1` as the CSS selector. That rule applies to elements with that class. + +
diff --git a/docs/10-Tutorials/index.md b/docs/10-Tutorials/index.md index 2c653621..96d7e0b1 100644 --- a/docs/10-Tutorials/index.md +++ b/docs/10-Tutorials/index.md @@ -27,6 +27,7 @@ The guides open with **Phoenix Pro**, using Design Mode for visual editing. Choo ## Work with text +- **[Edit text and change fonts](/docs/tutorials/edit-text-fonts):** change a heading, choose its font, and adjust its size using Pro's visual controls or Community's HTML and CSS steps. - **[Find in Files](/docs/Features/find-in-files):** search across your project and open a matching line. - **[Replace text in one file](/docs/tutorials/find-and-replace):** change a word or phrase in the file you have open. - **[Replace text across files](/docs/tutorials/replace-in-files):** review matches and apply selected changes across your project. diff --git a/docusaurus.config.js b/docusaurus.config.js index a4694aa1..76002d59 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -144,6 +144,7 @@ const config = { ], plugins: [ "@docsearch/docusaurus-adapter", + "./plugins/tutorial-icons", ["./plugins/tutorial-media", { publish: process.env.PHCODE_PUBLISH_TUTORIAL_VIDEOS === "1", publicationsFile: process.env.PHCODE_VIDEO_PUBLICATIONS_FILE, diff --git a/package.json b/package.json index 4f16ca2b..508f04b5 100644 --- a/package.json +++ b/package.json @@ -6,7 +6,7 @@ "docusaurus": "docusaurus", "test:tutorials": "node --test --test-reporter=tap scripts/tutorial-release.test.cjs", "test:links": "node --test --test-reporter=tap scripts/verify-links.test.cjs", - "test:search": "node --test --test-reporter=tap scripts/search-tabs.test.cjs scripts/search-crawler.test.cjs scripts/docsearch-package.test.cjs", + "test:search": "node --test --test-reporter=tap scripts/search-tabs.test.cjs scripts/search-crawler.test.cjs scripts/docsearch-package.test.cjs scripts/tutorial-icons.test.cjs", "package:tutorials": "node scripts/package-tutorials.cjs", "verify:tutorials": "node scripts/verify-tutorials.cjs", "verify:links": "node scripts/verify-links.cjs", diff --git a/plugins/tutorial-icons/index.js b/plugins/tutorial-icons/index.js new file mode 100644 index 00000000..e0cb3a4e --- /dev/null +++ b/plugins/tutorial-icons/index.js @@ -0,0 +1,35 @@ +const fs = require('node:fs/promises'); +const path = require('node:path'); +const React = require('react'); +const {renderToStaticMarkup} = require('react-dom/server'); +const icons = require('../../src/components/TutorialIcon/icons'); + +// The article and these image files share the same SVG geometry. Export images +// for Markdown consumers without changing the article's inline, themed icons. +function renderIcon(name, active = false) { + const icon = icons[name]; + if (!icon) throw new Error(`Unknown tutorial icon: ${name}`); + const light = active ? '#a85b00' : '#606770'; + const dark = active ? '#f8a949' : '#dadde1'; + const theme = `svg{color:${light}}@media(prefers-color-scheme:dark){svg{color:${dark}}}`; + return '\n' + renderToStaticMarkup(React.cloneElement(icon, { + xmlns: 'http://www.w3.org/2000/svg', width: 20, height: 20, + }, React.createElement('style', null, theme), icon.props.children)); +} + +module.exports = function tutorialIcons() { + return { + name: 'tutorial-icon-images', + async postBuild({outDir}) { + const directory = path.join(outDir, 'img/tutorial-icons'); + await fs.mkdir(directory, {recursive: true}); + await Promise.all(Object.keys(icons).flatMap(name => [false, true].map(active => + fs.writeFile(path.join(directory, `${name}${active ? '-active' : ''}.svg`), renderIcon(name, active))))); + await Promise.all(['sources.json', 'LICENSE-FONT-AWESOME.txt', 'LICENSE-BOOTSTRAP-ICONS.txt'].map(file => + fs.copyFile(path.join(__dirname, '../../src/components/TutorialIcon', file), path.join(directory, file)))); + console.log(`[tutorial-icons] Exported ${Object.keys(icons).length} control shapes in two states.`); + }, + }; +}; + +module.exports.renderIcon = renderIcon; diff --git a/scripts/search-crawler.test.cjs b/scripts/search-crawler.test.cjs index dfca4dec..feeffa07 100644 --- a/scripts/search-crawler.test.cjs +++ b/scripts/search-crawler.test.cjs @@ -178,6 +178,31 @@ test('AI extraction keeps descriptions when inline images have no usable source } }); +test('AI extraction keeps published control icons inline and restores the article SVGs', () => { + const context = fixture('https://docs.phcode.dev/docs/guide', '

Click lightning bolt, then orange pen.

'); + const original = context.$.html(); + context.helpers.markdown = selector => context.$(selector).html(); + const [record] = extractMarkdownRecords(context); + assert.match(record.text, /src="https:\/\/docs\.phcode\.dev\/img\/tutorial-icons\/preview\.svg" alt="lightning bolt icon"/); + assert.match(record.text, /src="https:\/\/docs\.phcode\.dev\/img\/tutorial-icons\/pen-active\.svg"/); + assert.doesNotMatch(record.text, / { throw new Error('conversion failed'); }; + assert.throws(() => extractMarkdownRecords(context), /conversion failed/); + assert.equal(context.$.html(), original); +}); + +test('control-icon annotations cannot introduce foreign, unsafe or unrelated image URLs', () => { + for (const source of ['https://other.test/img/tutorial-icons/preview.svg', 'javascript:alert(1)', 'data:image/svg+xml,svg', '/img/other.svg', '/img/tutorial-icons/preview.svg?mode=unknown']) { + const context = fixture('https://docs.phcode.dev/docs/guide', `
lightning bolt
`); + const original = context.$.html(); + context.helpers.markdown = selector => context.$(selector).html(); + const [record] = extractMarkdownRecords(context); + assert.doesNotMatch(record.text, / { const actions = vm.runInNewContext(`(${renderActions()})`, {URL, URLSearchParams}); assert.deepEqual(Array.from(actions, action => action.indexName), ['phcode', 'markdown-index']); diff --git a/scripts/tutorial-icons.test.cjs b/scripts/tutorial-icons.test.cjs new file mode 100644 index 00000000..e1b12007 --- /dev/null +++ b/scripts/tutorial-icons.test.cjs @@ -0,0 +1,43 @@ +const {test} = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('node:fs/promises'); +const os = require('node:os'); +const path = require('node:path'); +const cheerio = require('cheerio'); +const plugin = require('../plugins/tutorial-icons'); +const icons = require('../src/components/TutorialIcon/icons'); +const sources = require('../src/components/TutorialIcon/sources.json'); + +test('exported icons retain the actual control shape, intrinsic size and theme support', () => { + assert.deepEqual(Object.keys(icons).sort(), Object.keys(sources.icons).sort()); + const $ = cheerio.load(plugin.renderIcon('preview'), {xmlMode: true}); + assert.equal($('svg').attr('viewBox'), '-8.5 7.5 24 24'); + assert.equal($('polygon').attr('points'), '6.5 18.5 .5 14.5 -7.5 24.5 .5 19.5 6.5 23.5 14.5 13.5'); + assert.equal($('svg').attr('width'), '20'); + assert.equal($('svg').attr('height'), '20'); + assert.match($('style').text(), /prefers-color-scheme:dark/); + assert.equal($('script,foreignObject,image,use').length, 0); + assert.match(plugin.renderIcon('pen', true), /#a85b00.*#f8a949/); + assert.throws(() => plugin.renderIcon('not-a-control'), /Unknown tutorial icon/); +}); + +test('production build exports every control and its attribution without changing source files', async () => { + const outDir = await fs.mkdtemp(path.join(os.tmpdir(), 'phcode-icons-')); + try { + await plugin().postBuild({outDir}); + const directory = path.join(outDir, 'img/tutorial-icons'); + for (const name of Object.keys(icons)) { + for (const active of [false, true]) { + const xml = await fs.readFile(path.join(directory, `${name}${active ? '-active' : ''}.svg`), 'utf8'); + assert.equal(cheerio.load(xml, {xmlMode: true})('svg').length, 1); + } + } + const attribution = JSON.parse(await fs.readFile(path.join(directory, 'sources.json'), 'utf8')); + assert.deepEqual(attribution, sources); + for (const file of ['LICENSE-FONT-AWESOME.txt', 'LICENSE-BOOTSTRAP-ICONS.txt']) { + assert.ok((await fs.readFile(path.join(directory, file), 'utf8')).length > 100); + } + } finally { + await fs.rm(outDir, {recursive: true, force: true}); + } +}); diff --git a/scripts/verify-search.cjs b/scripts/verify-search.cjs index f448d77a..a6795b8d 100644 --- a/scripts/verify-search.cjs +++ b/scripts/verify-search.cjs @@ -29,7 +29,18 @@ function verifySearchBuild(buildDirectory = path.resolve(__dirname, '../build')) assert.equal(result.searchParams.get('edition'), edition, 'Search result must select the target edition'); assert.equal(result.hash, `#${anchor}`, 'Search result must keep its target section'); } - console.log('Search release checks passed: robots instructions and edition-specific section links.'); + const tutorial = readPage('docs/tutorials/add-images.html'); + const inlineIcons = tutorial('svg[data-tutorial-icon-src]'); + assert.ok(inlineIcons.length > 0, 'Tutorial control icons need published image URLs for Ask AI'); + inlineIcons.each((_, element) => { + const url = tutorial(element).attr('data-tutorial-icon-src'); + assert.match(url, /^\/img\/tutorial-icons\/[a-zA-Z][a-zA-Z0-9-]*\.svg$/); + const xml = fs.readFileSync(path.join(buildDirectory, url.slice(1)), 'utf8'); + const $ = cheerio.load(xml, {xmlMode: true}); + assert.equal($('svg').attr('viewBox'), tutorial(element).attr('viewBox'), `${url}: control geometry must match the article`); + assert.equal($('svg').attr('width'), '20', `${url}: icons must have an intrinsic inline size`); + }); + console.log('Search release checks passed: robots, edition links, and published control icons.'); } if (require.main === module) verifySearchBuild(process.argv[2]); diff --git a/scripts/verify-tutorials.cjs b/scripts/verify-tutorials.cjs index 6504f1ce..8d5f8b1b 100644 --- a/scripts/verify-tutorials.cjs +++ b/scripts/verify-tutorials.cjs @@ -16,7 +16,7 @@ const ORIGIN = 'https://docs.phcode.dev'; const GUIDES = ['tutorials', 'tutorials/add-images', 'tutorials/link-pages', 'tutorials/share-website', 'tutorials/bootstrap', 'tutorials/run-python', 'tutorials/find-and-replace', 'tutorials/replace-in-files', 'Features/find-in-files', - 'tutorials/image-text-layout']; + 'tutorials/image-text-layout', 'tutorials/edit-text-fonts']; const BLOGS = ['how-to-convert-png-to-pdf-free-online', 'how-to-convert-png-to-pdf-without-losing-quality']; const ARTICLE_ROUTES = [...GUIDES.map(guide => '/docs/' + guide), ...BLOGS.map(slug => '/blog/' + slug)]; const WATCH_VIDEOS = [...Object.values(imageVideos), ...Object.values(pngPdfVideos), ...Object.values(layoutVideos)]; diff --git a/src/components/TutorialIcon/icons.js b/src/components/TutorialIcon/icons.js index 3cb6d513..d3080e8c 100644 --- a/src/components/TutorialIcon/icons.js +++ b/src/components/TutorialIcon/icons.js @@ -1,25 +1,26 @@ // Icon geometry from Phoenix Code, Bootstrap Icons, and bundled Font Awesome Free 6.1.2. // Source paths and attribution are recorded in sources.json and the adjacent license files. -import React from 'react'; +const React = require('react'); +const h = React.createElement; -export default { - layout: (), - startProject: (), - search: (), - showInTree: (), - expand: (), - restore: (), - pen: (), - modes: (), - save: (), - laptop: (), - gallery: (), - link: (), - insert: (), - add: (), - chooseImage: (), - close: (), - share: (), - popout: (), - preview: (), +module.exports = { + layout: h("svg", { viewBox: "0 0 24 24", fill: "none" }, h("rect", { x: "3.5", y: "3.5", width: "17", height: "17", rx: "2", stroke: "currentColor", strokeWidth: "1.8" }), h("path", { d: "M3.5 9.5h17M10 9.5v11", stroke: "currentColor", strokeWidth: "1.8" })), + startProject: h("svg", { viewBox: "0 0 16 16", fill: "currentColor" }, h("path", { d: "m.5 3 .04.87a1.99 1.99 0 0 0-.342 1.311l.637 7A2 2 0 0 0 2.826 14H9v-1H2.826a1 1 0 0 1-.995-.91l-.637-7A1 1 0 0 1 2.19 4h11.62a1 1 0 0 1 .996 1.09L14.54 8h1.005l.256-2.819A2 2 0 0 0 13.81 3H9.828a2 2 0 0 1-1.414-.586l-.828-.828A2 2 0 0 0 6.172 1H2.5a2 2 0 0 0-2 2zm5.672-1a1 1 0 0 1 .707.293L7.586 3H2.19c-.24 0-.47.042-.683.12L1.5 2.98a1 1 0 0 1 1-.98h3.672z" }), h("path", { d: "M13.5 10a.5.5 0 0 1 .5.5V12h1.5a.5.5 0 1 1 0 1H14v1.5a.5.5 0 1 1-1 0V13h-1.5a.5.5 0 0 1 0-1H13v-1.5a.5.5 0 0 1 .5-.5z" })), + search: h("svg", { viewBox: "0 0 16 16", fill: "currentColor" }, h("path", { d: "M11.742 10.344a6.5 6.5 0 1 0-1.397 1.398h-.001c.03.04.062.078.098.115l3.85 3.85a1 1 0 0 0 1.415-1.414l-3.85-3.85a1.007 1.007 0 0 0-.115-.1zM12 6.5a5.5 5.5 0 1 1-11 0 5.5 5.5 0 0 1 11 0z" })), + showInTree: h("svg", { viewBox: "0 0 16 16", fill: "currentColor" }, h("path", { d: "M4.5 1A1.5 1.5 0 0 0 3 2.5V3h4v-.5A1.5 1.5 0 0 0 5.5 1h-1zM7 4v1h2V4h4v.882a.5.5 0 0 0 .276.447l.895.447A1.5 1.5 0 0 1 15 7.118V13H9v-1.5a.5.5 0 0 1 .146-.354l.854-.853V9.5a.5.5 0 0 0-.5-.5h-3a.5.5 0 0 0-.5.5v.793l.854.853A.5.5 0 0 1 7 11.5V13H1V7.118a1.5 1.5 0 0 1 .83-1.342l.894-.447A.5.5 0 0 0 3 4.882V4h4zM1 14v.5A1.5 1.5 0 0 0 2.5 16h3A1.5 1.5 0 0 0 7 14.5V14H1zm8 0v.5a1.5 1.5 0 0 0 1.5 1.5h3a1.5 1.5 0 0 0 1.5-1.5V14H9zm4-11H9v-.5A1.5 1.5 0 0 1 10.5 1h1A1.5 1.5 0 0 1 13 2.5V3z" })), + expand: h("svg", { viewBox: "0 0 448 512", fill: "currentColor" }, h("path", { d: "M128 32H32C14.31 32 0 46.31 0 64v96c0 17.69 14.31 32 32 32s32-14.31 32-32V96h64c17.69 0 32-14.31 32-32S145.7 32 128 32zM416 32h-96c-17.69 0-32 14.31-32 32s14.31 32 32 32h64v64c0 17.69 14.31 32 32 32s32-14.31 32-32V64C448 46.31 433.7 32 416 32zM128 416H64v-64c0-17.69-14.31-32-32-32s-32 14.31-32 32v96c0 17.69 14.31 32 32 32h96c17.69 0 32-14.31 32-32S145.7 416 128 416zM416 320c-17.69 0-32 14.31-32 32v64h-64c-17.69 0-32 14.31-32 32s14.31 32 32 32h96c17.69 0 32-14.31 32-32v-96C448 334.3 433.7 320 416 320z" })), + restore: h("svg", { viewBox: "0 0 448 512", fill: "currentColor" }, h("path", { d: "M128 320H32c-17.69 0-32 14.31-32 32s14.31 32 32 32h64v64c0 17.69 14.31 32 32 32s32-14.31 32-32v-96C160 334.3 145.7 320 128 320zM416 320h-96c-17.69 0-32 14.31-32 32v96c0 17.69 14.31 32 32 32s32-14.31 32-32v-64h64c17.69 0 32-14.31 32-32S433.7 320 416 320zM320 192h96c17.69 0 32-14.31 32-32s-14.31-32-32-32h-64V64c0-17.69-14.31-32-32-32s-32 14.31-32 32v96C288 177.7 302.3 192 320 192zM128 32C110.3 32 96 46.31 96 64v64H32C14.31 128 0 142.3 0 160s14.31 32 32 32h96c17.69 0 32-14.31 32-32V64C160 46.31 145.7 32 128 32z" })), + pen: h("svg", { viewBox: "0 0 512 512", fill: "currentColor" }, h("path", { d: "M421.7 220.3L188.5 453.4L154.6 419.5L158.1 416H112C103.2 416 96 408.8 96 400V353.9L92.51 357.4C87.78 362.2 84.31 368 82.42 374.4L59.44 452.6L137.6 429.6C143.1 427.7 149.8 424.2 154.6 419.5L188.5 453.4C178.1 463.8 165.2 471.5 151.1 475.6L30.77 511C22.35 513.5 13.24 511.2 7.03 504.1C.8198 498.8-1.502 489.7 .976 481.2L36.37 360.9C40.53 346.8 48.16 333.9 58.57 323.5L291.7 90.34L421.7 220.3zM492.7 58.75C517.7 83.74 517.7 124.3 492.7 149.3L444.3 197.7L314.3 67.72L362.7 19.32C387.7-5.678 428.3-5.678 453.3 19.32L492.7 58.75z" })), + modes: h("svg", { viewBox: "0 0 320 512", fill: "currentColor" }, h("path", { d: "M310.6 246.6l-127.1 128C176.4 380.9 168.2 384 160 384s-16.38-3.125-22.63-9.375l-127.1-128C.2244 237.5-2.516 223.7 2.438 211.8S19.07 192 32 192h255.1c12.94 0 24.62 7.781 29.58 19.75S319.8 237.5 310.6 246.6z" })), + save: h("svg", { viewBox: "0 0 448 512", fill: "currentColor" }, h("path", { d: "M433.1 129.1l-83.9-83.9C342.3 38.32 327.1 32 316.1 32H64C28.65 32 0 60.65 0 96v320c0 35.35 28.65 64 64 64h320c35.35 0 64-28.65 64-64V163.9C448 152.9 441.7 137.7 433.1 129.1zM224 416c-35.34 0-64-28.66-64-64s28.66-64 64-64s64 28.66 64 64S259.3 416 224 416zM320 208C320 216.8 312.8 224 304 224h-224C71.16 224 64 216.8 64 208v-96C64 103.2 71.16 96 80 96h224C312.8 96 320 103.2 320 112V208z" })), + laptop: h("svg", { viewBox: "0 0 640 512", fill: "currentColor" }, h("path", { d: "M128 96h384v256h64v-272c0-26.38-21.62-48-48-48h-416c-26.38 0-48 21.62-48 48V352h64V96zM624 383.1h-608c-8.75 0-16 7.25-16 16v16c0 35.25 28.75 64 64 64h512c35.25 0 64-28.75 64-64v-16C640 391.2 632.8 383.1 624 383.1z" })), + gallery: h("svg", { viewBox: "0 0 24 24", fill: "currentColor" }, h("path", { d: "M21 19V5c0-1.1-.9-2-2-2H5c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2zM8.5 13.5l2.5 3.01L14.5 12l4.5 6H5l3.5-4.5z" }), h("path", { d: "M1 3v16h2V5h16V3H1z" })), + link: h("svg", { viewBox: "0 0 640 640", fill: "currentColor" }, h("path", { d: "M451.5 160C434.9 160 418.8 164.5 404.7 172.7C388.9 156.7 370.5 143.3 350.2 133.2C378.4 109.2 414.3 96 451.5 96C537.9 96 608 166 608 252.5C608 294 591.5 333.8 562.2 363.1L491.1 434.2C461.8 463.5 422 480 380.5 480C294.1 480 224 410 224 323.5C224 322 224 320.5 224.1 319C224.6 301.3 239.3 287.4 257 287.9C274.7 288.4 288.6 303.1 288.1 320.8C288.1 321.7 288.1 322.6 288.1 323.4C288.1 374.5 329.5 415.9 380.6 415.9C405.1 415.9 428.6 406.2 446 388.8L517.1 317.7C534.4 300.4 544.2 276.8 544.2 252.3C544.2 201.2 502.8 159.8 451.7 159.8zM307.2 237.3C305.3 236.5 303.4 235.4 301.7 234.2C289.1 227.7 274.7 224 259.6 224C235.1 224 211.6 233.7 194.2 251.1L123.1 322.2C105.8 339.5 96 363.1 96 387.6C96 438.7 137.4 480.1 188.5 480.1C205 480.1 221.1 475.7 235.2 467.5C251 483.5 269.4 496.9 289.8 507C261.6 530.9 225.8 544.2 188.5 544.2C102.1 544.2 32 474.2 32 387.7C32 346.2 48.5 306.4 77.8 277.1L148.9 206C178.2 176.7 218 160.2 259.5 160.2C346.1 160.2 416 230.8 416 317.1C416 318.4 416 319.7 416 321C415.6 338.7 400.9 352.6 383.2 352.2C365.5 351.8 351.6 337.1 352 319.4C352 318.6 352 317.9 352 317.1C352 283.4 334 253.8 307.2 237.5z" })), + insert: h("svg", { viewBox: "0 0 24 24", fill: "currentColor" }, h("path", { d: "M12 3.5C12.8284 3.5 13.5 4.17157 13.5 5V10.5H19C19.8284 10.5 20.5 11.1716 20.5 12C20.5 12.8284 19.8284 13.5 19 13.5H13.5V19C13.5 19.8284 12.8284 20.5 12 20.5C11.1716 20.5 10.5 19.8284 10.5 19V13.5H5C4.17157 13.5 3.5 12.8284 3.5 12C3.5 11.1716 4.17157 10.5 5 10.5H10.5V5C10.5 4.17157 11.1716 3.5 12 3.5Z" })), + add: h("svg", { viewBox: "0 0 16 16", fill: "none" }, h("path", { d: "M3 8h10M8 3v10", stroke: "currentColor", strokeWidth: "1.5", strokeLinecap: "round" })), + chooseImage: h("svg", { viewBox: "0 0 24 24", fill: "currentColor" }, h("path", { d: "M11 5v6H5v2h6v6h2v-6h6v-2h-6V5h-2z" })), + close: h("svg", { viewBox: "0 0 24 24", fill: "currentColor" }, h("path", { d: "M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41z", stroke: "currentColor", strokeWidth: "1", strokeLinecap: "round" })), + share: h("svg", { fill: "currentColor", viewBox: "0 0 24 24" }, h("path", { transform: "translate(3 4)", fill: "currentColor", d: "M11 2.5a2.5 2.5 0 1 1 .603 1.628l-6.718 3.12a2.499 2.499 0 0 1 0 1.504l6.718 3.12a2.5 2.5 0 1 1-.488.876l-6.718-3.12a2.5 2.5 0 1 1 0-3.256l6.718-3.12A2.5 2.5 0 0 1 11 2.5z" })), + popout: h("svg", { viewBox: "0 0 24 24", fill: "currentColor" }, h("g", { transform: "translate(3 2)" }, h("path", { transform: "translate(1 2)", fill: "currentColor", fillRule: "evenodd", d: "M8.636 3.5a.5.5 0 0 0-.5-.5H1.5A1.5 1.5 0 0 0 0 4.5v10A1.5 1.5 0 0 0 1.5 16h10a1.5 1.5 0 0 0 1.5-1.5V7.864a.5.5 0 0 0-1 0V14.5a.5.5 0 0 1-.5.5h-10a.5.5 0 0 1-.5-.5v-10a.5.5 0 0 1 .5-.5h6.636a.5.5 0 0 0 .5-.5z" }), h("path", { transform: "translate(1 2)", fill: "currentColor", fillRule: "evenodd", d: "M16 .5a.5.5 0 0 0-.5-.5h-5a.5.5 0 0 0 0 1h3.793L6.146 9.146a.5.5 0 1 0 .708.708L15 1.707V5.5a.5.5 0 0 0 1 0v-5z" }))), + preview: h("svg", { viewBox: "-8.5 7.5 24 24", fill: "currentColor" }, h("polygon", { points: "6.5 18.5 .5 14.5 -7.5 24.5 .5 19.5 6.5 23.5 14.5 13.5", transform: "translate(0 1)" })) }; diff --git a/src/components/TutorialIcon/index.js b/src/components/TutorialIcon/index.js index 1b997175..56f04d7b 100644 --- a/src/components/TutorialIcon/index.js +++ b/src/components/TutorialIcon/index.js @@ -1,15 +1,18 @@ import React, {cloneElement} from 'react'; +import useBaseUrl from '@docusaurus/useBaseUrl'; import icons from './icons'; import styles from './styles.module.css'; // Always pair an icon with its written name in the instructions. export default function TutorialIcon({name, label, active = false}) { + const imageUrl = useBaseUrl(`/img/tutorial-icons/${name}${active ? '-active' : ''}.svg`); if (!icons[name]) throw new Error(`Unknown tutorial icon: ${name}`); const icon = cloneElement(icons[name], { className: `${styles.icon}${active ? ` ${styles.active}` : ''}`, 'aria-hidden': true, focusable: 'false', 'data-tutorial-icon': name, + 'data-tutorial-icon-src': imageUrl, }); const [firstWord, ...remainingWords] = label.split(' '); return ( diff --git a/src/css/docsearch-syntax.css b/src/css/docsearch-syntax.css index 47c6f082..c858fcdd 100644 --- a/src/css/docsearch-syntax.css +++ b/src/css/docsearch-syntax.css @@ -1,4 +1,18 @@ /* Scope syntax colors to AI answers; ordinary documentation uses its own theme. */ +/* Control icons are inline images, unlike the larger instructional screenshots. */ +.DocSearch-Markdown-Content img[src*="/img/tutorial-icons/"] { + display: inline-block; + width: 1.25em; + height: 1.25em; + margin: 0 0.1em; + vertical-align: -0.25em; + color-scheme: light; +} + +[data-theme='dark'] .DocSearch-Markdown-Content img[src*="/img/tutorial-icons/"] { + color-scheme: dark; +} + .DocSearch-CodeSnippet { --ai-code-background: #f6f8fa; --ai-code-text: #24292f; diff --git a/static/tutorials/media/text-font-community-css.png b/static/tutorials/media/text-font-community-css.png new file mode 100644 index 00000000..59489b26 Binary files /dev/null and b/static/tutorials/media/text-font-community-css.png differ diff --git a/static/tutorials/media/text-font-community-html.png b/static/tutorials/media/text-font-community-html.png new file mode 100644 index 00000000..ba38dbf4 Binary files /dev/null and b/static/tutorials/media/text-font-community-html.png differ diff --git a/static/tutorials/media/text-font-pro-edit.png b/static/tutorials/media/text-font-pro-edit.png new file mode 100644 index 00000000..c473e0c0 Binary files /dev/null and b/static/tutorials/media/text-font-pro-edit.png differ diff --git a/static/tutorials/media/text-font-pro-font-picker.png b/static/tutorials/media/text-font-pro-font-picker.png new file mode 100644 index 00000000..3029207f Binary files /dev/null and b/static/tutorials/media/text-font-pro-font-picker.png differ