From d0c69cb7fc553adc7ab4fdf15d1f07ea0cfc1656 Mon Sep 17 00:00:00 2001 From: Charly Abraham Date: Wed, 18 Nov 2026 10:18:33 +0530 Subject: [PATCH 1/2] fix(search): preserve edition links and improve Ask AI answers Add crawler-visible tab metadata and edition-aware records so search links open the relevant instructions. Document input text colors with accurate Pro and Community workflows, improve ranking, and preserve complete AI walkthroughs with source screenshots. Use a reviewed DocSearch source build to preserve encoded URLs and name the Sidepanel dialog. Add JavaScript regression and build checks, correct search robots metadata, and document upgrades and deployment/recrawl order. Validation: clean npm ci; 24 search, 14 tutorial/link, and 6 vendor tests; production build; link, tutorial, and search verifiers; desktop/mobile browser checks. Existing unrelated blog/API build warnings remain. --- .github/workflows/build-verify.yml | 2 + .github/workflows/gh-pages-deploy.yml | 2 + AGENTS.md | 34 + README.md | 15 +- config/search/README.md | 153 ++ config/search/agent-instructions.md | 86 + config/search/evaluation.json | 14 + config/search/records.cjs | 153 ++ config/search/settings.cjs | 29 + docs/02-Live Preview/03-styles-bar.md | 2 + docs/04-Editing & Code/02-editing-colors.md | 30 + docusaurus.config.js | 9 +- package-lock.json | 200 +- package.json | 12 +- plugins/search-tabs/record-url.js | 26 + plugins/search-tabs/rehype.js | 94 + scripts/docsearch-package.test.cjs | 147 ++ scripts/search-crawler.cjs | 32 + scripts/search-crawler.test.cjs | 128 ++ scripts/search-tabs.test.cjs | 208 ++ scripts/verify-search.cjs | 36 + src/theme/SearchPage/index.js | 2 +- vendor/docsearch-react/.gitignore | 4 + vendor/docsearch-react/LICENSE | 21 + vendor/docsearch-react/README.md | 78 + .../docsearch-react/build/getBundleBanner.ts | 14 + vendor/docsearch-react/package-lock.json | 1987 +++++++++++++++++ vendor/docsearch-react/package.json | 99 + .../docsearch-react-5.2.0-phcode.1.tgz | Bin 0 -> 1131843 bytes .../src/AggregatedSearchBlock.tsx | 85 + vendor/docsearch-react/src/AlgoliaLogo.tsx | 81 + vendor/docsearch-react/src/AskAiScreen.tsx | 498 +++++ .../docsearch-react/src/AskAiScreenState.tsx | 203 ++ .../src/ConversationHistoryScreen.tsx | 69 + vendor/docsearch-react/src/DocSearch.tsx | 202 ++ vendor/docsearch-react/src/DocSearchAI.tsx | 202 ++ .../src/DocSearchAskAiModal.tsx | 694 ++++++ .../docsearch-react/src/DocSearchButton.tsx | 118 + vendor/docsearch-react/src/DocSearchModal.tsx | 306 +++ vendor/docsearch-react/src/ErrorScreen.tsx | 30 + vendor/docsearch-react/src/Footer.tsx | 122 + vendor/docsearch-react/src/Hit.tsx | 12 + .../docsearch-react/src/MemoizedMarkdown.tsx | 87 + vendor/docsearch-react/src/Menu.tsx | 107 + vendor/docsearch-react/src/ModalHeading.tsx | 20 + .../src/NewConversationScreen.tsx | 49 + .../docsearch-react/src/NoResultsScreen.tsx | 89 + vendor/docsearch-react/src/Results.tsx | 270 +++ vendor/docsearch-react/src/ResultsScreen.tsx | 108 + vendor/docsearch-react/src/ScreenState.tsx | 96 + vendor/docsearch-react/src/Sidepanel.tsx | 195 ++ .../src/Sidepanel/AggregatedSearchBlock.tsx | 37 + .../Sidepanel/ConversationHistoryScreen.tsx | 74 + .../src/Sidepanel/ConversationScreen.tsx | 374 ++++ .../src/Sidepanel/NewConversationScreen.tsx | 53 + .../src/Sidepanel/PromptForm.tsx | 227 ++ .../src/Sidepanel/Sidepanel.tsx | 484 ++++ .../src/Sidepanel/SidepanelButton.tsx | 85 + .../src/Sidepanel/SidepanelHeader.tsx | 196 ++ vendor/docsearch-react/src/Sidepanel/index.ts | 2 + .../src/Sidepanel/setSidepanelSearchClient.ts | 16 + vendor/docsearch-react/src/Sidepanel/types.ts | 7 + .../src/Sidepanel/useManageSidepanelLayout.ts | 74 + .../Sidepanel/useSidepanelKeyboardEvents.ts | 47 + .../src/Sidepanel/useSidepanelWidth.ts | 32 + vendor/docsearch-react/src/Snippet.tsx | 35 + vendor/docsearch-react/src/askai.ts | 114 + .../src/components/AskAiSearchBox.tsx | 328 +++ .../src/components/AskAiStartScreen.tsx | 32 + .../ConversationPromptSuggestions.tsx | 48 + .../src/components/FacetBar.tsx | 361 +++ .../src/components/FeedbackActions.tsx | 507 +++++ .../src/components/HitResultBadge.tsx | 66 + .../src/components/KeywordSearchBox.tsx | 79 + .../src/components/KeywordStartScreen.tsx | 28 + .../src/components/SourcesPanel.tsx | 106 + .../src/components/ToolCall.tsx | 231 ++ .../src/components/ui/Chip.tsx | 28 + .../src/components/ui/HitContent.tsx | 16 + .../src/components/ui/Menu.tsx | 120 + .../src/components/ui/ModalShell.tsx | 77 + .../src/components/ui/Popover.tsx | 68 + .../ui/RecentConversationsResults.tsx | 64 + .../src/components/ui/SearchBoxForm.tsx | 153 ++ .../components/ui/StoredSearchesSections.tsx | 122 + .../src/components/ui/ToolState.tsx | 24 + vendor/docsearch-react/src/constants.ts | 4 + .../src/constants/keyboardShortcuts.ts | 26 + vendor/docsearch-react/src/docsearchUtils.ts | 1 + .../src/hooks/useDocSearchFacets.ts | 153 ++ .../src/hooks/useDocSearchInsights.ts | 27 + .../src/hooks/useDocSearchModalEffects.ts | 62 + .../src/hooks/useInitialModalQuery.ts | 19 + .../src/hooks/useModalEnvironment.ts | 42 + .../docsearch-react/src/hooks/useModalRefs.ts | 23 + .../src/hooks/usePlatformKeys.ts | 27 + .../src/hooks/useRefreshOnInitialQuery.ts | 21 + .../src/hooks/useRelativeFormattedDate.ts | 39 + .../src/hooks/useSaveRecentSearch.ts | 59 + .../src/hooks/useStoredDocSearches.ts | 36 + .../docsearch-react/src/icons/AlertIcon.tsx | 22 + vendor/docsearch-react/src/icons/BackIcon.tsx | 29 + .../docsearch-react/src/icons/CheckIcon.tsx | 20 + .../docsearch-react/src/icons/ChevronIcon.tsx | 19 + .../docsearch-react/src/icons/CloseIcon.tsx | 18 + .../src/icons/ConversationHistoryIcon.tsx | 18 + vendor/docsearch-react/src/icons/EditIcon.tsx | 21 + .../docsearch-react/src/icons/ErrorIcon.tsx | 18 + .../docsearch-react/src/icons/ExpandIcon.tsx | 21 + .../docsearch-react/src/icons/FolderIcon.tsx | 20 + .../src/icons/GoToExternalIcon.tsx | 13 + .../docsearch-react/src/icons/LoadingIcon.tsx | 32 + .../docsearch-react/src/icons/MemoryIcon.tsx | 20 + .../docsearch-react/src/icons/MessageIcon.tsx | 19 + .../src/icons/MoreVerticalIcon.tsx | 20 + .../src/icons/NewConversationIcon.tsx | 27 + .../src/icons/NoResultsIcon.tsx | 22 + vendor/docsearch-react/src/icons/PinIcon.tsx | 20 + .../docsearch-react/src/icons/RecentIcon.tsx | 18 + .../docsearch-react/src/icons/SearchIcon.tsx | 37 + .../docsearch-react/src/icons/SelectIcon.tsx | 23 + vendor/docsearch-react/src/icons/SendIcon.tsx | 21 + .../docsearch-react/src/icons/SourceIcon.tsx | 75 + .../src/icons/SparklesIcon.tsx | 28 + vendor/docsearch-react/src/icons/StarIcon.tsx | 15 + vendor/docsearch-react/src/icons/StopIcon.tsx | 20 + vendor/docsearch-react/src/icons/ToolIcon.tsx | 20 + vendor/docsearch-react/src/icons/index.ts | 27 + vendor/docsearch-react/src/index.ts | 8 + vendor/docsearch-react/src/stored-searches.ts | 143 ++ vendor/docsearch-react/src/types/AskiAi.ts | 138 ++ .../docsearch-react/src/types/DocSearchHit.ts | 90 + .../src/types/DocSearchState.ts | 18 + .../src/types/DocSearchTheme.ts | 1 + vendor/docsearch-react/src/types/Feedback.ts | 30 + .../src/types/InternalDocSearchHit.ts | 5 + .../src/types/KeyboardShortcuts.ts | 14 + .../src/types/StoredDocSearchHit.ts | 23 + .../src/types/SuggestedQuestions.ts | 13 + vendor/docsearch-react/src/types/index.ts | 8 + vendor/docsearch-react/src/useAskAi.ts | 319 +++ .../src/useDocSearchKeyboardEvents.ts | 99 + vendor/docsearch-react/src/useFacetValues.ts | 89 + vendor/docsearch-react/src/useIsMobile.ts | 23 + vendor/docsearch-react/src/useSearchClient.ts | 34 + .../src/useSuggestedQuestions.ts | 50 + vendor/docsearch-react/src/useTheme.tsx | 24 + vendor/docsearch-react/src/useTouchEvents.ts | 36 + vendor/docsearch-react/src/useTrapFocus.ts | 41 + vendor/docsearch-react/src/utils/ai.ts | 383 ++++ .../src/utils/askAiBlockingMatchers.ts | 170 ++ .../docsearch-react/src/utils/capitalize.ts | 3 + .../docsearch-react/src/utils/collections.ts | 23 + .../src/utils/createAskAiSources.ts | 184 ++ .../src/utils/createDocSearchSources.ts | 333 +++ .../src/utils/decodeHtmlEntities.ts | 8 + vendor/docsearch-react/src/utils/facets.ts | 129 ++ .../src/utils/getHitItemBreadcrumbs.ts | 28 + .../src/utils/getNestedValue.ts | 32 + vendor/docsearch-react/src/utils/groupBy.ts | 21 + .../src/utils/groupConsecutiveToolResults.ts | 58 + vendor/docsearch-react/src/utils/identity.ts | 3 + vendor/docsearch-react/src/utils/index.ts | 14 + .../src/utils/isComposingKey.ts | 26 + .../src/utils/isModifierEvent.ts | 17 + .../docsearch-react/src/utils/isQueryEmpty.ts | 7 + vendor/docsearch-react/src/utils/keyboard.ts | 6 + vendor/docsearch-react/src/utils/markdown.ts | 57 + .../src/utils/mergeFacetFilters.ts | 185 ++ vendor/docsearch-react/src/utils/noop.ts | 1 + .../src/utils/normalizeDocSearchIndexes.ts | 17 + .../src/utils/removeHighlightTags.ts | 26 + vendor/docsearch-react/src/utils/sanitize.ts | 90 + vendor/docsearch-react/src/utils/scrollTo.ts | 9 + vendor/docsearch-react/src/utils/storage.ts | 190 ++ vendor/docsearch-react/src/version.ts | 1 + vendor/docsearch-react/style/askai.js | 1 + vendor/docsearch-react/style/button.js | 1 + vendor/docsearch-react/style/index.js | 1 + vendor/docsearch-react/style/modal.js | 1 + vendor/docsearch-react/style/sidepanel.js | 1 + vendor/docsearch-react/style/variables.js | 1 + .../tests/regressions.test.cjs | 130 ++ vendor/docsearch-react/tsconfig.json | 26 + vendor/docsearch-react/tsdown.base.ts | 11 + vendor/docsearch-react/tsdown.config.mts | 91 + vendor/docsearch-react/upstream-files.json | 167 ++ vendor/docsearch-react/upstream.patch | 81 + 188 files changed, 16354 insertions(+), 162 deletions(-) create mode 100644 config/search/README.md create mode 100644 config/search/agent-instructions.md create mode 100644 config/search/evaluation.json create mode 100644 config/search/records.cjs create mode 100644 config/search/settings.cjs create mode 100644 plugins/search-tabs/record-url.js create mode 100644 plugins/search-tabs/rehype.js create mode 100644 scripts/docsearch-package.test.cjs create mode 100644 scripts/search-crawler.cjs create mode 100644 scripts/search-crawler.test.cjs create mode 100644 scripts/search-tabs.test.cjs create mode 100644 scripts/verify-search.cjs create mode 100644 vendor/docsearch-react/.gitignore create mode 100644 vendor/docsearch-react/LICENSE create mode 100644 vendor/docsearch-react/README.md create mode 100644 vendor/docsearch-react/build/getBundleBanner.ts create mode 100644 vendor/docsearch-react/package-lock.json create mode 100644 vendor/docsearch-react/package.json create mode 100644 vendor/docsearch-react/releases/docsearch-react-5.2.0-phcode.1.tgz create mode 100644 vendor/docsearch-react/src/AggregatedSearchBlock.tsx create mode 100644 vendor/docsearch-react/src/AlgoliaLogo.tsx create mode 100644 vendor/docsearch-react/src/AskAiScreen.tsx create mode 100644 vendor/docsearch-react/src/AskAiScreenState.tsx create mode 100644 vendor/docsearch-react/src/ConversationHistoryScreen.tsx create mode 100644 vendor/docsearch-react/src/DocSearch.tsx create mode 100644 vendor/docsearch-react/src/DocSearchAI.tsx create mode 100644 vendor/docsearch-react/src/DocSearchAskAiModal.tsx create mode 100644 vendor/docsearch-react/src/DocSearchButton.tsx create mode 100644 vendor/docsearch-react/src/DocSearchModal.tsx create mode 100644 vendor/docsearch-react/src/ErrorScreen.tsx create mode 100644 vendor/docsearch-react/src/Footer.tsx create mode 100644 vendor/docsearch-react/src/Hit.tsx create mode 100644 vendor/docsearch-react/src/MemoizedMarkdown.tsx create mode 100644 vendor/docsearch-react/src/Menu.tsx create mode 100644 vendor/docsearch-react/src/ModalHeading.tsx create mode 100644 vendor/docsearch-react/src/NewConversationScreen.tsx create mode 100644 vendor/docsearch-react/src/NoResultsScreen.tsx create mode 100644 vendor/docsearch-react/src/Results.tsx create mode 100644 vendor/docsearch-react/src/ResultsScreen.tsx create mode 100644 vendor/docsearch-react/src/ScreenState.tsx create mode 100644 vendor/docsearch-react/src/Sidepanel.tsx create mode 100644 vendor/docsearch-react/src/Sidepanel/AggregatedSearchBlock.tsx create mode 100644 vendor/docsearch-react/src/Sidepanel/ConversationHistoryScreen.tsx create mode 100644 vendor/docsearch-react/src/Sidepanel/ConversationScreen.tsx create mode 100644 vendor/docsearch-react/src/Sidepanel/NewConversationScreen.tsx create mode 100644 vendor/docsearch-react/src/Sidepanel/PromptForm.tsx create mode 100644 vendor/docsearch-react/src/Sidepanel/Sidepanel.tsx create mode 100644 vendor/docsearch-react/src/Sidepanel/SidepanelButton.tsx create mode 100644 vendor/docsearch-react/src/Sidepanel/SidepanelHeader.tsx create mode 100644 vendor/docsearch-react/src/Sidepanel/index.ts create mode 100644 vendor/docsearch-react/src/Sidepanel/setSidepanelSearchClient.ts create mode 100644 vendor/docsearch-react/src/Sidepanel/types.ts create mode 100644 vendor/docsearch-react/src/Sidepanel/useManageSidepanelLayout.ts create mode 100644 vendor/docsearch-react/src/Sidepanel/useSidepanelKeyboardEvents.ts create mode 100644 vendor/docsearch-react/src/Sidepanel/useSidepanelWidth.ts create mode 100644 vendor/docsearch-react/src/Snippet.tsx create mode 100644 vendor/docsearch-react/src/askai.ts create mode 100644 vendor/docsearch-react/src/components/AskAiSearchBox.tsx create mode 100644 vendor/docsearch-react/src/components/AskAiStartScreen.tsx create mode 100644 vendor/docsearch-react/src/components/ConversationPromptSuggestions.tsx create mode 100644 vendor/docsearch-react/src/components/FacetBar.tsx create mode 100644 vendor/docsearch-react/src/components/FeedbackActions.tsx create mode 100644 vendor/docsearch-react/src/components/HitResultBadge.tsx create mode 100644 vendor/docsearch-react/src/components/KeywordSearchBox.tsx create mode 100644 vendor/docsearch-react/src/components/KeywordStartScreen.tsx create mode 100644 vendor/docsearch-react/src/components/SourcesPanel.tsx create mode 100644 vendor/docsearch-react/src/components/ToolCall.tsx create mode 100644 vendor/docsearch-react/src/components/ui/Chip.tsx create mode 100644 vendor/docsearch-react/src/components/ui/HitContent.tsx create mode 100644 vendor/docsearch-react/src/components/ui/Menu.tsx create mode 100644 vendor/docsearch-react/src/components/ui/ModalShell.tsx create mode 100644 vendor/docsearch-react/src/components/ui/Popover.tsx create mode 100644 vendor/docsearch-react/src/components/ui/RecentConversationsResults.tsx create mode 100644 vendor/docsearch-react/src/components/ui/SearchBoxForm.tsx create mode 100644 vendor/docsearch-react/src/components/ui/StoredSearchesSections.tsx create mode 100644 vendor/docsearch-react/src/components/ui/ToolState.tsx create mode 100644 vendor/docsearch-react/src/constants.ts create mode 100644 vendor/docsearch-react/src/constants/keyboardShortcuts.ts create mode 100644 vendor/docsearch-react/src/docsearchUtils.ts create mode 100644 vendor/docsearch-react/src/hooks/useDocSearchFacets.ts create mode 100644 vendor/docsearch-react/src/hooks/useDocSearchInsights.ts create mode 100644 vendor/docsearch-react/src/hooks/useDocSearchModalEffects.ts create mode 100644 vendor/docsearch-react/src/hooks/useInitialModalQuery.ts create mode 100644 vendor/docsearch-react/src/hooks/useModalEnvironment.ts create mode 100644 vendor/docsearch-react/src/hooks/useModalRefs.ts create mode 100644 vendor/docsearch-react/src/hooks/usePlatformKeys.ts create mode 100644 vendor/docsearch-react/src/hooks/useRefreshOnInitialQuery.ts create mode 100644 vendor/docsearch-react/src/hooks/useRelativeFormattedDate.ts create mode 100644 vendor/docsearch-react/src/hooks/useSaveRecentSearch.ts create mode 100644 vendor/docsearch-react/src/hooks/useStoredDocSearches.ts create mode 100644 vendor/docsearch-react/src/icons/AlertIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/BackIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/CheckIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/ChevronIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/CloseIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/ConversationHistoryIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/EditIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/ErrorIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/ExpandIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/FolderIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/GoToExternalIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/LoadingIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/MemoryIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/MessageIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/MoreVerticalIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/NewConversationIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/NoResultsIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/PinIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/RecentIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/SearchIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/SelectIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/SendIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/SourceIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/SparklesIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/StarIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/StopIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/ToolIcon.tsx create mode 100644 vendor/docsearch-react/src/icons/index.ts create mode 100644 vendor/docsearch-react/src/index.ts create mode 100644 vendor/docsearch-react/src/stored-searches.ts create mode 100644 vendor/docsearch-react/src/types/AskiAi.ts create mode 100644 vendor/docsearch-react/src/types/DocSearchHit.ts create mode 100644 vendor/docsearch-react/src/types/DocSearchState.ts create mode 100644 vendor/docsearch-react/src/types/DocSearchTheme.ts create mode 100644 vendor/docsearch-react/src/types/Feedback.ts create mode 100644 vendor/docsearch-react/src/types/InternalDocSearchHit.ts create mode 100644 vendor/docsearch-react/src/types/KeyboardShortcuts.ts create mode 100644 vendor/docsearch-react/src/types/StoredDocSearchHit.ts create mode 100644 vendor/docsearch-react/src/types/SuggestedQuestions.ts create mode 100644 vendor/docsearch-react/src/types/index.ts create mode 100644 vendor/docsearch-react/src/useAskAi.ts create mode 100644 vendor/docsearch-react/src/useDocSearchKeyboardEvents.ts create mode 100644 vendor/docsearch-react/src/useFacetValues.ts create mode 100644 vendor/docsearch-react/src/useIsMobile.ts create mode 100644 vendor/docsearch-react/src/useSearchClient.ts create mode 100644 vendor/docsearch-react/src/useSuggestedQuestions.ts create mode 100644 vendor/docsearch-react/src/useTheme.tsx create mode 100644 vendor/docsearch-react/src/useTouchEvents.ts create mode 100644 vendor/docsearch-react/src/useTrapFocus.ts create mode 100644 vendor/docsearch-react/src/utils/ai.ts create mode 100644 vendor/docsearch-react/src/utils/askAiBlockingMatchers.ts create mode 100644 vendor/docsearch-react/src/utils/capitalize.ts create mode 100644 vendor/docsearch-react/src/utils/collections.ts create mode 100644 vendor/docsearch-react/src/utils/createAskAiSources.ts create mode 100644 vendor/docsearch-react/src/utils/createDocSearchSources.ts create mode 100644 vendor/docsearch-react/src/utils/decodeHtmlEntities.ts create mode 100644 vendor/docsearch-react/src/utils/facets.ts create mode 100644 vendor/docsearch-react/src/utils/getHitItemBreadcrumbs.ts create mode 100644 vendor/docsearch-react/src/utils/getNestedValue.ts create mode 100644 vendor/docsearch-react/src/utils/groupBy.ts create mode 100644 vendor/docsearch-react/src/utils/groupConsecutiveToolResults.ts create mode 100644 vendor/docsearch-react/src/utils/identity.ts create mode 100644 vendor/docsearch-react/src/utils/index.ts create mode 100644 vendor/docsearch-react/src/utils/isComposingKey.ts create mode 100644 vendor/docsearch-react/src/utils/isModifierEvent.ts create mode 100644 vendor/docsearch-react/src/utils/isQueryEmpty.ts create mode 100644 vendor/docsearch-react/src/utils/keyboard.ts create mode 100644 vendor/docsearch-react/src/utils/markdown.ts create mode 100644 vendor/docsearch-react/src/utils/mergeFacetFilters.ts create mode 100644 vendor/docsearch-react/src/utils/noop.ts create mode 100644 vendor/docsearch-react/src/utils/normalizeDocSearchIndexes.ts create mode 100644 vendor/docsearch-react/src/utils/removeHighlightTags.ts create mode 100644 vendor/docsearch-react/src/utils/sanitize.ts create mode 100644 vendor/docsearch-react/src/utils/scrollTo.ts create mode 100644 vendor/docsearch-react/src/utils/storage.ts create mode 100644 vendor/docsearch-react/src/version.ts create mode 100644 vendor/docsearch-react/style/askai.js create mode 100644 vendor/docsearch-react/style/button.js create mode 100644 vendor/docsearch-react/style/index.js create mode 100644 vendor/docsearch-react/style/modal.js create mode 100644 vendor/docsearch-react/style/sidepanel.js create mode 100644 vendor/docsearch-react/style/variables.js create mode 100644 vendor/docsearch-react/tests/regressions.test.cjs create mode 100644 vendor/docsearch-react/tsconfig.json create mode 100644 vendor/docsearch-react/tsdown.base.ts create mode 100644 vendor/docsearch-react/tsdown.config.mts create mode 100644 vendor/docsearch-react/upstream-files.json create mode 100644 vendor/docsearch-react/upstream.patch diff --git a/.github/workflows/build-verify.yml b/.github/workflows/build-verify.yml index f6eaa5d50..d730426fa 100644 --- a/.github/workflows/build-verify.yml +++ b/.github/workflows/build-verify.yml @@ -25,6 +25,8 @@ jobs: run: npm run test:tutorials - name: Test link verification run: npm run test:links + - name: Test search links and DocSearch fixes + run: npm run test:search - name: Package tutorial projects run: npm run package:tutorials - name: Build website diff --git a/.github/workflows/gh-pages-deploy.yml b/.github/workflows/gh-pages-deploy.yml index dabb52934..0276ca847 100644 --- a/.github/workflows/gh-pages-deploy.yml +++ b/.github/workflows/gh-pages-deploy.yml @@ -33,6 +33,8 @@ jobs: run: npm run test:tutorials - name: Test link verification run: npm run test:links + - name: Test search links and DocSearch fixes + run: npm run test:search - name: Package tutorial projects run: npm run package:tutorials - name: Restore original video publication dates diff --git a/AGENTS.md b/AGENTS.md index 380c668d2..913222036 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,3 +10,37 @@ Keep verification code in JavaScript. For video or implementation changes, follo 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. + +## Package upgrades and DocSearch maintenance + +Before preparing a release, maintaining dependencies, or changing search/Ask AI, +check the live npm registry and official release notes for newer stable DocSearch +and Docusaurus versions. Compare them with `package.json`, `package-lock.json`, +and the upstream version recorded in any vendored package. Do not assume the +installed version or a cached search result is the latest release. For DocSearch: + +```sh +npm view @docsearch/react dist-tags --json +``` + +While `@docsearch/react` uses a local `file:` dependency, ordinary `npm update` +will not bring Algolia's changes into that package. Follow the +[DocSearch maintenance notes](vendor/docsearch-react/README.md) when upgrading: + +- Check whether the official release fixes encoded URLs and the Sidepanel's + accessible name, including its header translations. Verify the behavior with + the regression cases; keep unsafe URL scheme rejection intact. +- If both fixes are included, return to the official package and retire the + custom build and override. Update packaging-specific tests while retaining + the behavior checks. +- If a fix is still missing, update the custom build to the newer compatible + upstream release and retain only the fixes still needed. Refresh its source, + provenance, reviewed diff, version, packaged artifact, and lockfile together. + +Keep related DocSearch packages compatible and run the +[search checks](README.md#search-and-ask-ai-checks), production build, and the +visual checks in the maintenance notes before releasing an upgrade. Record the +check date, current and latest upstream versions, and the upgrade outcome or +reason for deferral in the maintenance notes or release handoff. These checks +require a contributor to run them; this note does not install an automatic +release monitor. diff --git a/README.md b/README.md index 7145d6807..97339b4d8 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ CC BY License Copyright (c) 2022-present, core.ai # Website -This website is built using [Docusaurus 2](https://docusaurus.io/), a modern +This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. ### Installation @@ -49,6 +49,19 @@ External site availability and temporary server errors still need live monitorin Run `npm run test:links` to test the checker. After a direct `npm run docusaurus -- build`, run `npm run verify:links` separately. +### Search and Ask AI checks + +Run `npm run test:search` before releasing search changes. The JavaScript tests +cover edition-specific links, crawler extraction, and the maintained DocSearch +package. Normal builds also run `npm run verify:search` to check the search page's +robots tag and tab metadata in the generated HTML. Run it separately after a +direct `npm run docusaurus -- build`. + +See [search configuration](config/search/README.md) for the supported Algolia +settings, agent instructions, deployment and recrawl order, and query checks. +The reviewed DocSearch source dependency has its own +[provenance, rebuild instructions, and removal criteria](vendor/docsearch-react/README.md). + ### Tutorial release checks Before adding or changing a video, read the diff --git a/config/search/README.md b/config/search/README.md new file mode 100644 index 000000000..6724de801 --- /dev/null +++ b/config/search/README.md @@ -0,0 +1,153 @@ +# Search and Ask AI maintenance + +The site uses `phcode` for keyword search and `markdown-index` for Ask AI. +Their extraction code is in [records.cjs](records.cjs); the hosted Crawler runs +the standalone functions generated from this source. No credentials belong in +this directory. + +## Apply changes in this order + +1. Run `npm run test:search`, build the site, and run `npm run verify:search`. + Also complete the [tutorial release checks](../../README.md#tutorial-release-checks). +2. Deploy the website before crawling when content or tab metadata has changed. +3. Run `node scripts/search-crawler.cjs --actions` from the repository root. + Replace the Crawler's two `actions` with this output. Preserve the application's + managed credentials, crawl scope, schedule, and safety checks. +4. Test a feature page, a mixed-edition tutorial, an individual blog article, and + a blog tag archive in Algolia's URL Tester. The archive should produce no + records; the other pages must remain searchable. Review and publish the configuration. +5. Run `node scripts/search-crawler.cjs --settings` and apply those deltas to + the existing indices through Algolia's settings UI or `setSettings` API. + Preserve settings not listed in the deltas. Put the same values in the + Crawler's `initialIndexSettings` for future new indices: those initial settings + do **not** update an existing index. +6. Copy [agent-instructions.md](agent-instructions.md) into this application's + Agent Studio agent prompt. Test both a mixed-edition question and an explicit + Community question, then save the instructions. Keep the existing provider, + model, and tools unless a separate change calls for updating them. +7. Recrawl once the deployed pages and extraction configuration are ready. + Review the crawl report and any publishing safety check. Removing duplicate + archives can reduce record counts; inspect that difference before approving + it instead of disabling the safety check. +8. Repeat [evaluation.json](evaluation.json) against the refreshed index and + inspect the actual browser results. Use `analytics: false` and + `clickAnalytics: false` for API diagnostics so test queries do not pollute + customer analytics. Test one real browser result click separately to confirm + that DocSearch Insights receives the event. + +## Why these settings and records matter + +- `attributeCriteriaComputedBy: "sum"` ranks all query words together. It prevents + one word in a page title from dominating a better multiword match in a section. + The 14-query comparison for this change improved `text color` and `text colour` + while preserving the intended Find in Files, PDF, release, and API results. + Keep `minProximity: 2`; lowering it favors joined API identifiers for some + user-facing feature searches. Do not tune settings from a single question. +- Both indices omit blog listings, tag archives, and the site's search page. + Individual articles and API documentation remain included and receive their + own category labels. No client-side result filtering hides these sources. +- The rehype plugin adds `data-search-params` to headings inside query-enabled + Docusaurus tabs. Extraction combines that metadata with the exact section + anchor, for example `?edition=community#copy-your-picture`. Docusaurus itself + selects the tab. Default Pro selection and the reading layout are preserved. + Existing bare-hash links are not rewritten at runtime. Tabs without an internal + heading cannot be assigned a section-specific selection by this mechanism. +- AI records include edition availability and labeled section links in the text + the model reads. Pro-only notices remain attached to every split record. + An absent edition marker means unspecified, not free. Instructions reinforce + these source boundaries, but generated answers still require sampled checks. +- The input-color guide documents the actual available controls. The Styles Bar + hides text controls for inputs; Pro users can edit `color` in the Layers panel, + and Community users can edit CSS. Search ranking cannot supply an undocumented + workflow or make a nonexistent control appear. + +## Dependency checks + +`@docsearch/react` is pinned to the reviewed source build in +[vendor/docsearch-react](../../vendor/docsearch-react/README.md). The npm override +ensures the adapter, modal, and sidepanel use the same package. Its fixes preserve +encoded URLs and give the Ask AI dialog an accessible name. Do not edit installed +dependencies, intercept global networking, or rewrite rendered citations. + +After changing the dependency, test an absolute URL containing `%20` in both an +AI answer and its Sources menu; verify that it reaches the correct guide. Check +full-page Ask AI submission, keyboard close/focus restoration, and desktop/mobile +layout. Once an upstream release passes these cases, retire the source fork as +described in its README. + +The search page uses `name="robots" content="noindex, follow"`. This applies to +the internal search page, not the documentation articles. An Algolia recrawl +does not request Google indexing. + +## Answer usefulness checks + +After changing agent instructions, test a fresh conversation as well as a +follow-up. Judge whether a beginner can finish the task, not just answer length. + +| Question | What a useful answer must contain | +| --- | --- | +| `how to add image` | 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. | +| `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. | +| `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. | +| `Show the Image Gallery screenshot from the tutorial` | A relevant source screenshot that loads, meaningful alternative text, a separate full-size link, and the source guide. Check that it fits the desktop and mobile answer panel. | + +Retain modes, dialogs, locations, and saving when shortening prose. A documentation +link can provide screenshots and optional practice files; it should not replace +essential instructions. These are manual checks of actual generated answers, +not keyword assertions that would confuse mentioning a control with explaining it. + +The existing DocSearch Markdown renderer supports inline images, and the Crawler's +Markdown keeps documentation image URLs and descriptions. The agent can use one +or two relevant screenshots in a visual walkthrough without a custom renderer. +Use standalone `![description](source-image-url)` followed by a separate full-size +link. Do not nest the image in a Markdown link: the current link renderer escapes +its inner HTML. Never construct image filenames or use a screenshot from the +wrong edition. Complete text steps still matter when no useful image is retrieved. + +## Verification recorded on 18 November 2026 + +- The live npm registry and official release notes were checked: DocSearch + `5.2.0` and Docusaurus `3.10.2` remain the latest stable releases and match this + site's upstream versions. DocSearch's current development revision + `1412418c58fc2a404b2bd4b5c450f318579877dd` still reproduces the encoded-URL + bug and lacks the Sidepanel's accessible name, so the reviewed + `5.2.0-phcode.1` build is retained. Recheck before the next release. +- A clean `npm ci` in an isolated directory installed the locked local package. + All 24 search regression tests passed against that installation; the adapter, + modal, sidepanel, and Docusaurus search theme resolved the same corrected + package and React instance. The tarball matched its lockfile integrity. +- The production build, local-link checks, tutorial release checks, and 24 + JavaScript search regression tests passed. Existing unrelated Docusaurus + anchor warnings remain outside this change. +- Chrome checks covered desktop and mobile search, light and dark appearance, + full-page Ask AI submission, highlighted CSS, Sources links, and Escape/focus + restoration. A real full-page result click received HTTP 200 from Insights. +- A built Community section link selected its tab and exposed the target + heading. Opening a tutorial without an edition query still selected Pro. +- Algolia's hosted URL Tester retained feature pages, mixed tutorials, and + individual articles, and returned no records for a blog tag archive. + A temporary test fixture supplied the same heading metadata as the new build; + the returned Markdown contained both edition labels and the exact section + links. This verifies that `helpers.markdown` consumes the Cheerio annotations. + The fixture was removed before publishing. +- Crawler configuration v5 and both existing index settings were saved and + read back. Crawl scope, schedule, and the 30% record-loss safety check were + preserved. The agent instructions were saved and sampled with Pro/Community + questions. Deploy the website changes, then recrawl before evaluating the new + input-color content or tab-aware links against the production index. +- After revising the prompt for complete walkthroughs and screenshots, fresh + image answers retained numbered steps and displayed relevant Pro and Community + images on the deployed site. Community replacement used Community screenshots; + Find and Replace kept the shared current-file workflow; the `alt` follow-up + stayed brief. Screenshots and full-size links loaded, and the answer panel had + no horizontal overflow at a 390 px viewport. These prompt changes are live + independently of the pending website deployment. + +## Official references + +- [Docusaurus query-string tabs](https://docusaurus.io/docs/markdown-features/tabs#query-string) +- [Algolia extraction actions](https://www.algolia.com/doc/tools/crawler/apis/configuration/actions/) +- [Algolia initial index settings](https://www.algolia.com/doc/tools/crawler/apis/configuration/initial-index-settings/) +- [Algolia attribute ranking strategies](https://www.algolia.com/doc/api-reference/api-parameters/attributeCriteriaComputedBy) +- [Google robots metadata](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) diff --git a/config/search/agent-instructions.md b/config/search/agent-instructions.md new file mode 100644 index 000000000..d4ef5a147 --- /dev/null +++ b/config/search/agent-instructions.md @@ -0,0 +1,86 @@ +You are a helpful AI assistant embedded in a documentation website: Phoenix Code (https://docs.phcode.dev). + The website stores its documentation data **exclusively** inside the index or indices: markdown-index. + + Phoenix Code is a code editor for web developers, designers, and students. It supports documented editor and terminal workflows beyond HTML, CSS, and JavaScript, including running Python in the desktop app. Your tone is warm, peer-to-peer, and inviting — + you want users to keep asking follow-up questions. Never "Happy to help!" or "Great question!", but also never stiff, distant, or rules-enforcing. Treat every question as welcome. + + ## Primary behavior — Phoenix Code questions + For questions about Phoenix Code's features, setup, troubleshooting, or best practices, answer from the provided index context. + - Interpret short task questions in the context of this Phoenix Code documentation site, even when the user does not say Phoenix Code. For example, 'How do I run Python?', 'How do I add an image?', and 'find and replace' are questions about using Phoenix Code. Do not require the user to repeat the product name. + - Search the documentation before deciding that an editor, coding, installation, terminal, or file-management task is unsupported or outside scope. A workflow documented in the index is in scope even when its language or tool is not a web-platform API. + - For Python, retrieve the Run your first Python program tutorial. Explain the desktop integrated terminal requirement, that Community and Pro use the same steps, and the operating-system commands from the guide. Link to https://docs.phcode.dev/docs/tutorials/run-python. If the operating system is not given, show the short Windows and macOS/Linux commands without making the user ask again. + - Prefer beginner tutorials for how-to questions. Distinguish Find in Files, replacing in one file, and replacing across files. Describe Community and Pro differences only where the documentation does. Never invent menus, icons, features, or shortcuts. + - When the docs offer different Phoenix Pro and Community workflows, show the Phoenix Pro visual workflow FIRST, followed by the Community (free) HTML/code workflow. Use clear edition headings. This ordering applies by default to adding, replacing, and resizing images. If the user explicitly asks about Community/free or Pro, prioritize the edition they requested. If both editions use identical steps, explain the shared workflow once instead of inventing differences. + - Answer accurately, with enough detail for the reader to complete the task. A short question is not a request for a shortened procedure. + - Before saying information is unavailable, double-check whether related content exists in the context. + - If related content exists, summarize it clearly rather than refusing. + - If nothing relevant exists, reply along these lines (vary phrasing): + *"I didn't find a match in the Phoenix Code docs for that exact phrasing. Want to rephrase, or tell me what you're trying to do? The feature might live under a different name — I can + point you at the right page once I know the workflow."* + If plausible-looking related features exist in the context (e.g. Live Preview, Emmet, extensions, themes), suggest 1–2 of them as "did you mean…". + - Always include the relevant phcode.dev URL when available. + + ## Actionable how-to answers + - For a task such as adding an image, assume the reader is new to Phoenix Code unless they say otherwise. Give a usable walkthrough, usually 4–8 short numbered steps per relevant edition. Use as many steps as the task needs; do not pad simple answers or compress an entire workflow into one sentence of menu arrows. + - State the starting point briefly: the project or file to open and any required file or installation. Then name the control, where to find it, and what to select. On first use, describe the documented icon shape alongside its label, such as the lightning bolt for Live Preview or the pen for Edit Mode. + - Include required modes before the actions that depend on them, how to turn those modes on, important file-picker or folder dialogs, how to apply or save the change, and the visible result the reader should check. Do not assume a beginner already has Edit Mode enabled. + - Follow references within the retrieved guide. If a short FAQ says to follow another section (such as "Choose your picture"), include the relevant steps from that section. An overview or FAQ alone is not a complete procedure. + - Keep adding a new item distinct from replacing an existing one. For example, adding an image in Pro needs the insertion step, selection of the new image, Image Gallery / Select from device, the image-folder prompt when shown, a description, and saving. Do not stop at "+ → Before or After → Image" or imply that this menu opens the device picker directly. Replacing an existing image starts by selecting that image instead. + - For a Community code workflow, say which file to edit and where the snippet belongs. Use a complete, language-labeled code example, explain the filenames or values to change, then include saving and checking Live Preview. For images, make the project's images-folder location and exact filename/extension clear. Use the documented Highlight Mode steps when locating existing HTML from the preview. + - Link the relevant guide for screenshots, a video, or the optional practice project after giving the essential steps. The link supplements the answer; it must not carry missing steps the reader needs to complete the task. + - Keep simple factual questions and narrow follow-ups short. Do not repeat both editions or an entire walkthrough when the user asks about just one step. Offer one relevant troubleshooting check when helpful instead of a generic closing question. + + ## Screenshots in answers + - For a visual how-to, include one or two useful screenshots when the retrieved documentation contains images that clarify the controls or result. Place each image beside the relevant instructions, under the correct edition. Keep the numbered steps; the image supplements them. Simple factual answers do not need an image. + - Reuse only screenshot URLs present in the retrieved source. Match the caption and surrounding instructions to the task and edition; never invent a URL, infer a filename, use an unrelated decorative image, or substitute a Pro screenshot for Community. If no suitable screenshot was retrieved, give the complete text steps and a link to the guide. + - Render each screenshot with standalone Markdown image syntax: ![Short description of the control or result](exact-image-url). Put a separate [View full-size screenshot](exact-image-url) link below it. Do not wrap an image inside a Markdown link, use an HTML img tag, or put the image Markdown in a code block. + - Preserve the exact URL, including percent encoding. Root-relative image URLs on docs.phcode.dev are supported. Keep descriptions meaningful for screen-reader users and cite the source guide alongside the related steps. + + ## Edition accuracy + - Treat edition labels in retrieved records and "Pro Feature" notices as authoritative. A Pro-only source does not document a Community workflow. + - Layers Panel, Styles Bar controls, and Live Preview Edit Mode are Phoenix Pro features. Never recommend those controls as available in Community (free), including in a sentence following a Community code example. + - Community users can edit HTML and CSS in the code editor and use the documented Live Preview workflow. Retrieve the relevant Community guide before describing its steps. Do not confuse Live Preview or Highlight Mode with Pro Edit Mode. + - When the user explicitly asks for Community/free, answer for that edition. If a requested visual control is Pro-only, say so briefly and give a documented code-editor alternative when available. + - When both editions are relevant and documented, put Phoenix Pro first and Community second. If the steps are shared, explain them once. + - Check that a visual control supports the selected element. The Styles Bar hides text controls for input and select elements. For input text colors, use the documented Layers panel Styles workflow in Pro, or edit the CSS color declaration in the code editor in Community. Do not invent an input-specific Styles Bar control. + - Before sending an answer, check every menu, panel, and visual control against its source edition. Keep Pro-only steps under the Pro heading and cite the source for each workflow. + + ## Search quality + - For Phoenix Code how-to questions, search with short, focused task or feature phrases rather than a long list of loosely related keywords. + - Prefer current tutorials and feature documentation. If the results are unrelated, archive/listing pages, or release summaries that do not explain the task, retry with simpler terms or the relevant feature name before answering. + - Retrieve the documented Phoenix Code workflow before falling back to general HTML or CSS advice. When the documentation supports separate workflows, present Phoenix Pro first, followed by Community (free), unless the user requested a particular edition. + - Cite the relevant tutorial or feature page. This assistant is embedded on https://docs.phcode.dev. For sources on docs.phcode.dev, use root-relative Markdown links with the exact encoded path and fragment from the source URL: for example, [Styles Bar guide](/docs/Pro%20Features/styles-bar) or [Layers panel](/docs/Pro%20Features/layers-panel). Preserve all percent encoding, query parameters, and fragments. If a source link selects a tab (for example, ?edition=community), keep that selection so the cited step is visible. Do not rewrite URL paths or invent section anchors. Use full HTTPS URLs for external sources such as MDN. Do not invent paths or cite tag archives or blog listings as how-to sources. + + ## Secondary behavior — HTML, CSS, and web-platform questions + Phoenix Code's users often ask general web-platform questions — HTML elements, CSS properties, JavaScript Web APIs. Treat these as welcome. They're the kind of question a Phoenix Code user + naturally has, and answering them warmly keeps the conversation going. + + 1. Open with a natural transition; vary the phrasing so it doesn't feel scripted. Examples: + - *"That's a general web-platform topic rather than a Phoenix Code feature, so here's the quick version —"* + - *"Not specific to Phoenix Code, but this is right in your wheelhouse as a web developer. Here's how it works —"* + - *"Web-platform question — happy to cover it since it's exactly what you'd build in Phoenix Code. Short version —"* + 2. Give a brief, correct answer from general web-development knowledge (2–4 sentences, or a small code example when useful). + 3. Append the canonical MDN link at the end for deeper reading, using these URL patterns: + - HTML element `` → `https://developer.mozilla.org/en-US/docs/Web/HTML/Element/` + - HTML global attribute → `https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/` + - CSS property `prop-name` → `https://developer.mozilla.org/en-US/docs/Web/CSS/` + - CSS at-rule `@name` → `https://developer.mozilla.org/en-US/docs/Web/CSS/@` + - JavaScript Web API `Interface` → `https://developer.mozilla.org/en-US/docs/Web/API/` + - Anything else web-platform related → link to the closest MDN section you can identify. + 4. When the question touches a Phoenix Code feature that handles it (Live Preview, CSS Quick Edit, HTML Validator, Emmet, etc.), close with a natural invitation to explore that feature — + e.g. *"If you want to see this live as you edit, Phoenix Code's Live Preview is the fastest way: "*. + + ## Out of scope + Only redirect questions that are unrelated to Phoenix Code, its documented workflows, HTML, CSS, or web-platform APIs (for example, unrelated personal advice). Running Python or another documented language in the editor is not out of scope. For a coding or tool question, check the index for a relevant Phoenix Code workflow before redirecting. When redirecting, avoid making the user feel dismissed: + *"That one's outside what I can help with here, but I'm all yours for Phoenix Code and web-platform questions — HTML, CSS, JavaScript, the editor itself. What are you working on?"* + Adjust the closing question to fit context so it feels like a real invitation, not a canned line. + + ## Style + - Use short, plain sentences and remove filler, while retaining necessary actions and explanations. How-to answers should be complete, not merely brief. No "Happy to help!" or "Great question!". + - Peer-to-peer, confident, warm. + - Use code blocks for code. + - Always include a language hint in code fences (e.g. ```js, ```css, ```html, ```bash, ```jsx, ```json, ```ts). Never use a bare triple-backtick fence — always label the language so the + code block can be syntax-highlighted. + - When it fits naturally, end an answer with a light next-step prompt (a related feature, a follow-up the user might have). Don't force this on every response — only when it genuinely adds + value. + - Never invent MDN URLs for pages you're not confident exist. If unsure, link to `https://developer.mozilla.org/` and let the user search from there. diff --git a/config/search/evaluation.json b/config/search/evaluation.json new file mode 100644 index 000000000..e281de0a3 --- /dev/null +++ b/config/search/evaluation.json @@ -0,0 +1,14 @@ +[ + {"query":"text color","expectedPath":"/docs/Pro%20Features/styles-bar#text-color","maxRank":3}, + {"query":"how to change input text colors","expectedPath":"/docs/editing-colors#change-input-text-colors","maxRank":5}, + {"query":"find in files","expectedPath":"/docs/Features/find-in-files","maxRank":1}, + {"query":"find and replace","expectedPath":"/docs/tutorials/find-and-replace","maxRank":3}, + {"query":"run python","expectedPath":"/docs/tutorials/run-python","maxRank":3}, + {"query":"image next to text","expectedPath":"/docs/tutorials/image-text-layout","maxRank":3}, + {"query":"copy your picture","expectedPath":"/docs/tutorials/add-images?edition=community#copy-your-picture","maxRank":3}, + {"query":"png to pdf quality","expectedPath":"/blog/how-to-convert-png-to-pdf-without-losing-quality","maxRank":3}, + {"query":"png to pdf free online","expectedPath":"/blog/how-to-convert-png-to-pdf-free-online","maxRank":3}, + {"query":"Phoenix Code 5.5","expectedPath":"/blog/release-5.5","maxRank":3}, + {"query":"getCandidateFiles","expectedPath":"/api/API-Reference/search/FindInFiles#getcandidatefilesscope--promise","maxRank":3}, + {"query":"CommandManager","expectedPath":"/api/API-Reference/command/CommandManager","maxRank":3} +] diff --git a/config/search/records.cjs b/config/search/records.cjs new file mode 100644 index 000000000..ae1fa9c33 --- /dev/null +++ b/config/search/records.cjs @@ -0,0 +1,153 @@ +const {addTabQueryToRecordUrl} = require('../../plugins/search-tabs/record-url'); + +/** + * First-party Crawler extraction. Keep this function self-contained: the hosted + * Crawler receives its source, together with the supported URL helper, from + * scripts/search-crawler.cjs. It uses only the Crawler's documented context. + */ +function extractSearchRecords({$, url, helpers}, format, resolveTabUrl) { + const pageUrl = new URL(url); + const path = decodeURIComponent(pageUrl.pathname).replace(/\/+$/, '') || '/'; + if (path === '/search' || path === '/blog' || path === '/blog/archive' || + /^\/blog\/(?:tags|page)(?:\/|$)/.test(path)) return []; + + const category = path.startsWith('/api/') ? 'API' : + path.startsWith('/blog/') ? 'Blog' : + path.startsWith('/videos/') ? 'Videos' : 'Documentation'; + const language = $('meta[name="docsearch:language"]').attr('content') || 'en'; + const parametersByAnchor = Object.create(null); + const editionSections = []; + const explicitEditions = ($('meta[name="docsearch:edition"]').attr('content') || '') + .split(',').map(value => value.trim()).filter(value => ['pro', 'community'].includes(value)); + let introductoryProNotice = false; + let reachedSection = false; + const contentRoot = $('main article').length ? $('main article').first() : $('main').first(); + contentRoot.find('h2, h3, h4, h5, h6, .theme-admonition').each((_, element) => { + const node = $(element); + // A Pro note inside a tab or a later section qualifies that section only. + if (node.closest('[role="tabpanel"]').length) return; + if (/^h[2-6]$/.test(element.tagName || element.name || '')) reachedSection = true; + if (!reachedSection && node.hasClass('theme-admonition') && + node.children().first().text().trim() === 'Pro Feature') introductoryProNotice = true; + }); + const pageIsPro = /^\/docs\/pro[ -]features\//i.test(path) || introductoryProNotice; + const knownEditions = new Set([...explicitEditions, ...(pageIsPro ? ['pro'] : [])]); + + $('h1[id], h2[id], h3[id], h4[id], h5[id], h6[id]').each((_, element) => { + const heading = $(element); + const parameters = heading.attr('data-search-params'); + if (!parameters) return; + const anchor = heading.attr('id'); + parametersByAnchor[anchor] = parameters; + const edition = new URLSearchParams(parameters).get('edition'); + if (!['pro', 'community'].includes(edition)) return; + knownEditions.add(edition); + const sectionUrl = new URL(pageUrl); + sectionUrl.hash = anchor; + editionSections.push({ + heading: heading.text().replace(/\u200b/g, '').trim(), + edition, + url: resolveTabUrl(sectionUrl.href, parametersByAnchor), + }); + }); + + const editions = [...knownEditions]; + // Absence of a Pro marker does not establish Community availability. + const edition = editions.length > 1 ? 'mixed' : editions[0] || 'unspecified'; + const baseMetadata = {category, edition, editions, lang: language}; + + if (format === 'docsearch') { + const records = helpers.docsearch({ + recordProps: { + lvl0: {selectors: '', defaultValue: category}, + lvl1: ['article h1', 'main h1', 'header h1', 'h1', 'head > title'], + lvl2: ['article h2', 'main h2', 'h2'], + lvl3: ['article h3', 'main h3', 'h3'], + lvl4: ['article h4', 'main h4', 'h4'], + lvl5: ['article h5', 'main h5', 'h5'], + lvl6: ['article h6', 'main h6', 'h6'], + content: ['article p, article li', 'main p, main li'], + }, + aggregateContent: true, + recordVersion: 'v3', + }); + return records.map(record => { + const recordUrl = resolveTabUrl(record.url, parametersByAnchor); + const target = new URL(recordUrl, pageUrl); + const selectedEdition = target.searchParams.get('edition'); + target.hash = ''; + return { + ...record, + ...baseMetadata, + ...(['pro', 'community'].includes(selectedEdition) ? { + edition: selectedEdition, + editions: [selectedEdition], + } : {}), + url: recordUrl, + url_without_anchor: target.href, + }; + }); + } + + if (format !== 'markdown') throw new Error(`Unsupported search format: ${format}`); + + // Make the edition boundaries readable in the model's actual text context, + // as well as in structured attributes. Restore the source DOM afterwards so + // another extraction action cannot inherit these indexing-only annotations. + const annotations = []; + let text; + try { + for (const section of editionSections) { + const label = section.edition === 'pro' ? 'Phoenix Pro' : 'Community (free)'; + const anchor = decodeURIComponent(new URL(section.url).hash.slice(1)); + const heading = $('[id]').filter((_, element) => $(element).attr('id') === anchor).first(); + const marker = $('').text(`[${label}] `); + heading.prepend(marker); + annotations.push(marker); + const source = $('

'); + source.append($('').attr('href', section.url).text(`${label}: ${section.heading}`)); + heading.after(source); + annotations.push(source); + } + text = helpers.markdown('main'); + } finally { + annotations.forEach(element => element.remove()); + } + if (!text || !text.trim()) return []; + + const heading = $('main h1').first().text().replace(/\u200b/g, '').trim(); + const title = heading || $('head > title').text().trim(); + const version = $('meta[name="docsearch:version"]').attr('content') || 'latest'; + const tags = $('meta[name="docsearch:docusaurus_tag"]').attr('content') || ''; + const availability = edition === 'pro' ? 'Edition availability: Phoenix Pro only.\n\n' : + edition === 'community' ? 'Edition availability: Community (free).\n\n' : + edition === 'mixed' ? 'Edition availability: this page has separate Phoenix Pro and Community (free) sections.\n\n' : ''; + const records = helpers.splitTextIntoRecords({ + text, + baseRecord: { + ...baseMetadata, + url: pageUrl.href, + objectID: pageUrl.href, + title, + heading, + language, + version: version.split(',').map(value => value.trim()).filter(Boolean), + docusaurus_tag: tags.split(',').map(value => value.trim()).filter(Boolean), + editionSections, + }, + // Reserve room for the repeated edition label in every returned chunk. + maxRecordBytes: 99000, + orderingAttributeName: 'part', + }); + return records.map(record => ({...record, text: availability + record.text})); +} + +function extractDocSearchRecords(context) { + return extractSearchRecords(context, 'docsearch', addTabQueryToRecordUrl); +} + +function extractMarkdownRecords(context) { + return extractSearchRecords(context, 'markdown', addTabQueryToRecordUrl); +} + +module.exports = {extractSearchRecords, extractDocSearchRecords, extractMarkdownRecords}; diff --git a/config/search/settings.cjs b/config/search/settings.cjs new file mode 100644 index 000000000..1359b4d8a --- /dev/null +++ b/config/search/settings.cjs @@ -0,0 +1,29 @@ +/** + * Explicit deltas for existing indices. initialIndexSettings only initializes + * new indices; publish these through Algolia's supported setSettings API/UI. + * Preserve other live index settings when applying these deltas. + * https://www.algolia.com/doc/tools/crawler/apis/configuration/initial-index-settings + */ +const indexSettings = { + phcode: { + attributesForFaceting: ['type', 'lang', 'category', 'edition', 'editions'], + attributesToRetrieve: [ + 'hierarchy', 'content', 'anchor', 'url', 'url_without_anchor', 'type', + 'category', 'edition', 'editions', + ], + removeStopWords: ['en'], + minProximity: 2, + attributeCriteriaComputedBy: 'sum', + }, + 'markdown-index': { + attributesForFaceting: [ + 'lang', 'language', 'version', 'docusaurus_tag', 'category', 'edition', 'editions', + ], + attributesToRetrieve: [ + 'title', 'heading', 'text', 'url', 'lang', 'language', 'version', + 'docusaurus_tag', 'category', 'edition', 'editions', 'editionSections', 'part', + ], + }, +}; + +module.exports = {indexSettings}; diff --git a/docs/02-Live Preview/03-styles-bar.md b/docs/02-Live Preview/03-styles-bar.md index 215dbec04..52bc3227f 100644 --- a/docs/02-Live Preview/03-styles-bar.md +++ b/docs/02-Live Preview/03-styles-bar.md @@ -131,6 +131,8 @@ Colors written as `oklch()`, `lab()`, or `color()` open in the picker too. The **Text color** button works the same way as [Background Color](#background-color), but it controls the color of the element's text. It opens the same color picker. +Text controls are not shown for `` or `