diff --git a/.codex/environments/environment.toml b/.codex/environments/environment.toml index df9fe419ab..f7c3c5551e 100644 --- a/.codex/environments/environment.toml +++ b/.codex/environments/environment.toml @@ -46,7 +46,7 @@ npm ci --prefix src/Exceptionless.Web/ClientApp --prefer-offline --no-audit echo "Installing legacy Angular frontend dependencies..." npm ci --prefix src/Exceptionless.Web/ClientApp.angular --prefer-offline --no-audit -echo "Setup complete. Use the Run Aspire action to start the app." +echo "Setup complete. Use the Run Aspire action to start the app, or Run Lume Docs to test the static site." ''' [cleanup] @@ -62,6 +62,8 @@ echo "Removing repo-local temp/test output only..." rm -rf .cache/tmp rm -rf .aspire rm -rf TestResults +rm -rf docs/_site +rm -rf docs/_cache find . -type d \( -name TestResults -o -name .vite -o -name .svelte-kit \) -exec rm -rf {} + @@ -80,14 +82,38 @@ cd "${CODEX_WORKTREE_PATH:?CODEX_WORKTREE_PATH is required}" export AppMode=Development export DOTNET_ENVIRONMENT=Development export ASPNETCORE_ENVIRONMENT=Development +export ASPIRE_HOME="$CODEX_WORKTREE_PATH/.aspire" if command -v aspire >/dev/null 2>&1; then + mkdir -p "$ASPIRE_HOME" aspire run --nologo --non-interactive else dotnet run --project src/Exceptionless.AppHost/Exceptionless.AppHost.csproj fi ''' +[[actions]] +name = "Run Lume Docs" +icon = "run" +command = ''' +set -e + +cd "${CODEX_WORKTREE_PATH:?CODEX_WORKTREE_PATH is required}/docs" + +export PORT="${PORT:-7141}" + +if ! command -v deno >/dev/null 2>&1; then + echo "deno is not installed or not on PATH. The Lume docs site requires Deno." >&2 + exit 1 +fi + +echo "deno:" +deno --version + +echo "Starting Lume docs at http://127.0.0.1:$PORT/" +deno task serve +''' + [[actions]] name = "Stop Aspire Containers, keep data" icon = "tool" diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml index 00531e089e..cf2a484f7c 100644 --- a/.github/workflows/website.yml +++ b/.github/workflows/website.yml @@ -21,6 +21,10 @@ jobs: defaults: run: working-directory: docs + env: + EXCEPTIONLESS_SITE_API_KEY: ${{ vars.EXCEPTIONLESS_SITE_API_KEY }} + EXCEPTIONLESS_SITE_SERVER_URL: ${{ vars.EXCEPTIONLESS_SITE_SERVER_URL }} + EXCEPTIONLESS_SITE_VERSION: ${{ github.sha }} steps: - name: Checkout diff --git a/.gitignore b/.gitignore index d1f62c2742..36508301c3 100644 --- a/.gitignore +++ b/.gitignore @@ -81,6 +81,7 @@ k8s/ex-*-snapshots.yaml tmpclaude* dogfood-output/ debug-storybook.log +.aspire/ docs/_cache/ .devcontainer/devcontainer-lock.json diff --git a/docs/_config.ts b/docs/_config.ts index d31c755189..e6f7aeda4d 100644 --- a/docs/_config.ts +++ b/docs/_config.ts @@ -63,9 +63,31 @@ site.hooks.markdownIt((markdownIt: any) => { site.data("docsNavHtml", docsNavHtml) site.data("siteDataJson", siteDataJson) site.data("copyrightYear", new Date().getFullYear()) +site.data("exceptionlessClientScriptSrc", exceptionlessClientScriptSrc()) export default site +function exceptionlessClientScriptSrc(): string { + const apiKey = (Deno.env.get("EXCEPTIONLESS_SITE_API_KEY") ?? "").trim() + if (!apiKey) { + return "" + } + + const params = new URLSearchParams({ apiKey }) + const serverUrl = (Deno.env.get("EXCEPTIONLESS_SITE_SERVER_URL") ?? "").trim() + + if (serverUrl) { + params.set("serverUrl", serverUrl) + } + + const version = (Deno.env.get("EXCEPTIONLESS_SITE_VERSION") ?? "").trim() + if (version) { + params.set("version", version) + } + + return `/assets/js/exceptionless-client.js?${params}` +} + function uniqueHeadingSlug(value: string, env: Record): string { const counts = getHeadingSlugCounts(env) const baseSlug = slugifyHeading(value) || "section" diff --git a/docs/_includes/layouts/base.vto b/docs/_includes/layouts/base.vto index 2e8171a9a5..eed5ab33e4 100644 --- a/docs/_includes/layouts/base.vto +++ b/docs/_includes/layouts/base.vto @@ -63,6 +63,15 @@
  • Pricing
  • News
  • Docs
    • +
  • + Search +
  • Log In
  • Sign Up
    • @@ -74,7 +83,35 @@ - {{ content }} +
    + {{ content }} +
    + + + {{ if exceptionlessClientScriptSrc }} + + {{ /if }} + {{ for script of extraScripts || [] }} {{ /for }} - + {{ for script of extraModuleScripts || [] }} + + {{ /for }} diff --git a/docs/_includes/layouts/docs.vto b/docs/_includes/layouts/docs.vto index 19cdd14025..d51764a0c5 100644 --- a/docs/_includes/layouts/docs.vto +++ b/docs/_includes/layouts/docs.vto @@ -3,18 +3,18 @@ layout: layouts/base.vto extraStyles: - /assets/css/prism.css --- -
    +

    Documentation

    -
    +
    -
    -
    - - -
    +
    + {{ docsNavHtml(search, url) }}
    @@ -22,21 +22,3 @@ extraStyles:
    - - diff --git a/docs/deno.json b/docs/deno.json index 720bedd653..e000b15472 100644 --- a/docs/deno.json +++ b/docs/deno.json @@ -1,14 +1,15 @@ { "tasks": { "lume": "deno run -P=lume lume/cli.ts", - "build": "deno task lume && deno task postbuild", - "serve": "deno task build && deno run --allow-read=_site --allow-net=localhost,127.0.0.1 scripts/serve.ts", + "build": "deno task lume && deno task postbuild && deno bundle --platform=browser --minify --config=deno.json scripts/browser/exceptionless-client.ts -o _site/assets/js/exceptionless-client.js", + "serve": "deno task build && deno run --allow-read=_site --allow-net=localhost,127.0.0.1 --allow-env=PORT scripts/serve.ts", "postbuild": "deno run --allow-read --allow-write scripts/postbuild.ts", - "check": "deno check _config.ts scripts/site-collections.ts scripts/postbuild.ts scripts/serve.ts scripts/verify-links.ts scripts/find-unused.ts", + "check": "deno check _config.ts scripts/browser/exceptionless-client.ts scripts/site-collections.ts scripts/postbuild.ts scripts/serve.ts scripts/verify-links.ts scripts/find-unused.ts", "verify": "deno task build && deno run --allow-read scripts/verify-links.ts", "unused": "deno task build && deno run --allow-read scripts/find-unused.ts" }, "imports": { + "@exceptionless/browser": "npm:@exceptionless/browser@3.2.1", "lume/": "https://cdn.jsdelivr.net/gh/lumeland/lume@3.2.6/" }, "nodeModulesDir": "auto", diff --git a/docs/deno.lock b/docs/deno.lock index a2f2375c2a..0afcdd7283 100644 --- a/docs/deno.lock +++ b/docs/deno.lock @@ -33,6 +33,7 @@ "jsr:@std/toml@^1.0.3": "1.0.11", "jsr:@std/yaml@1.1.0": "1.1.0", "jsr:@std/yaml@^1.0.5": "1.1.0", + "npm:@exceptionless/browser@3.2.1": "3.2.1", "npm:@resvg/resvg-wasm@2.6.2": "2.6.2", "npm:esbuild@0.28.0": "0.28.0", "npm:highlight.js@11.11.1": "11.11.1", @@ -295,6 +296,16 @@ "os": ["win32"], "cpu": ["x64"] }, + "@exceptionless/browser@3.2.1": { + "integrity": "sha512-oPzCIrjEehS6wlPNu1VAUElbTd4nGv+DI1V72k3WDdCk6dsEFqVuWMbROdhBjk/RqoAJo84N5NDMdtPIFGqJ7w==", + "dependencies": [ + "@exceptionless/core", + "stacktrace-js" + ] + }, + "@exceptionless/core@3.2.1": { + "integrity": "sha512-JA4Wwkh9E6K4pJb9/cKR/SmJap5sqUvoi+eFQAKup2ZoliIPO5eSzx6Afb4R7R+N0imxjxQMj5kjcKRfA3X+1w==" + }, "@img/colour@1.1.0": { "integrity": "sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ==" }, @@ -462,6 +473,12 @@ "entities@4.5.0": { "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==" }, + "error-stack-parser@2.1.4": { + "integrity": "sha512-Sk5V6wVazPhq5MhpO+AUxJn5x7XSXGl1R93Vn7i+zS15KDVxQijejNCrz8340/2bgLBjR9GtEG8ZVKONDjcqGQ==", + "dependencies": [ + "stackframe" + ] + }, "esbuild@0.28.0": { "integrity": "sha512-sNR9MHpXSUV/XB4zmsFKN+QgVG82Cc7+/aaxJ8Adi8hyOac+EXptIp45QBPaVyX3N70664wRbTcLTOemCAnyqw==", "optionalDependencies": [ @@ -576,6 +593,33 @@ ], "scripts": true }, + "source-map@0.5.6": { + "integrity": "sha512-MjZkVp0NHr5+TPihLcadqnlVoGIoWo4IBHptutGh9wI3ttUYvCG26HkSuDi+K6lsZ25syXJXcctwgyVCt//xqA==" + }, + "stack-generator@2.0.10": { + "integrity": "sha512-mwnua/hkqM6pF4k8SnmZ2zfETsRUpWXREfA/goT8SLCV4iOFa4bzOX2nDipWAZFPTjLvQB82f5yaodMVhK0yJQ==", + "dependencies": [ + "stackframe" + ] + }, + "stackframe@1.3.4": { + "integrity": "sha512-oeVtt7eWQS+Na6F//S4kJ2K2VbRlS9D43mAlMyVpVWovy9o+jfgH8O9agzANzaiLjclA0oYzUXEM4PurhSUChw==" + }, + "stacktrace-gps@3.1.2": { + "integrity": "sha512-GcUgbO4Jsqqg6RxfyTHFiPxdPqF+3LFmQhm7MgCuYQOYuWyqxo5pwRPz5d/u6/WYJdEnWfK4r+jGbyD8TSggXQ==", + "dependencies": [ + "source-map", + "stackframe" + ] + }, + "stacktrace-js@2.0.2": { + "integrity": "sha512-Je5vBeY4S1r/RnLydLl0TBTi3F2qdfWmYsGvtfZgEI+SCprPppaIhQf5nGcal4gI4cGpCV/duLcAzT1np6sQqg==", + "dependencies": [ + "error-stack-parser", + "stack-generator", + "stacktrace-gps" + ] + }, "tslib@2.8.1": { "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==" }, @@ -731,5 +775,10 @@ "https://cdn.jsdelivr.net/gh/ventojs/vento@2.3.1/plugins/set.ts": "cbe42b771a04203b6fc1c178e655fa2536ab90ae67e52c083cf7c71f37c62711", "https://cdn.jsdelivr.net/gh/ventojs/vento@2.3.1/plugins/trim.ts": "8d33271327b09ffd8f569ebde85125b1324fa9538a54d6072ac97a9fb5d24264", "https://cdn.jsdelivr.net/gh/ventojs/vento@2.3.1/plugins/unescape.ts": "1c56f0310c7757880df7684fc6b7bf9efd27fdb6b929b89626802f5a99cb93ee" + }, + "workspace": { + "dependencies": [ + "npm:@exceptionless/browser@3.2.1" + ] } } diff --git a/docs/public/assets/css/custom.css b/docs/public/assets/css/custom.css index 54cfd80f5b..04eedee3c0 100644 --- a/docs/public/assets/css/custom.css +++ b/docs/public/assets/css/custom.css @@ -81,7 +81,7 @@ body, input, button, select, textarea, .search-query {font-family: Open Sans;} } .toc-list a:only-child { - color:#777 !important; + color: #777 !important; font-weight: 400; border-bottom: none; } @@ -262,32 +262,10 @@ body, input, button, select, textarea, .search-query { font-family: "Open Sans", Arial, sans-serif; } -#wrap h1, -#wrap h2, -#wrap h3, -.home h1, -.home h2, -.home h3, -.docs h1, -.docs h2, -.docs h3, -.toc-list a { - color: #4f7600 !important; -} - .page-header h1 { color: #9c9c9c !important; } -#wrap a:not(.btn), -.docs a, -.entry-content a, -.well a, -.row a:not(.btn), -.page #content p a { - color: #4f7600 !important; -} - #wrap .howDoesWork a, .howDoesWork a { color: #578f01 !important; @@ -303,7 +281,6 @@ body, input, button, select, textarea, .search-query { color: #ebebeb !important; } -.toc-list a:only-child, .cycloneslider-slide p { color: #555 !important; } @@ -449,3 +426,158 @@ body, input, button, select, textarea, .search-query { margin-left: 64px; } } + +body.site-search-open { + overflow: hidden; +} + +.site-search-modal[hidden] { + display: none; +} + +.site-search-form { + margin: 0; +} + +.site-search-body { + padding: 15px 15px 0; +} + +.site-search-input-row { + display: flex; + align-items: center; + min-width: 0; + border: 1px solid #b9b9b9; + border-radius: 4px; + background: #fff; +} + +.site-search-input-row:focus-within { + border-color: #598e0e; + box-shadow: 0 0 6px rgba(89, 142, 14, 0.35); +} + +.site-search-input-row i { + flex: 0 0 auto; + margin-left: 12px; + color: #777; +} + +#site-search-input { + box-sizing: border-box; + flex: 1 1 auto; + min-width: 0; + width: auto; + height: 42px; + margin: 0; + border: 0; + box-shadow: none; + color: #333; + font-size: 18px; + line-height: 42px; +} + +#site-search-input:focus { + outline: none; + box-shadow: none; +} + +.site-search-clear { + flex: 0 0 auto; + box-sizing: border-box; + width: 36px; + height: 36px; + margin-right: 4px; + padding: 0; + border: 0; + border-radius: 18px; + background: transparent; + color: #777; + font-size: 24px; + line-height: 34px; + text-align: center; +} + +.site-search-clear:hover, +.site-search-clear:focus { + background: #eeeeee; + color: #333; + outline: none; +} + +.site-search-status { + min-height: 20px; + margin: 0 -15px; + padding: 10px 15px; + border-bottom: 1px solid #eeeeee; + color: #777; +} + +.site-search-results { + margin: 0 -15px; + list-style: none; +} + +.site-search-result { + margin: 0; + padding: 14px 18px; + border-bottom: 1px solid #eeeeee; +} + +.site-search-result.is-active { + background: #f3f7ed; +} + +.site-search-result-title { + display: block; + color: #578f01 !important; + font-size: 18px; + font-weight: 700; + line-height: 1.3; +} + +.site-search-result-url { + margin: 3px 0 7px; + color: #777; + font-size: 12px; + line-height: 1.4; + word-break: break-word; +} + +.site-search-result-excerpt { + margin: 0; + color: #333; + font-size: 14px; + line-height: 1.55; +} + +.site-search-result mark { + padding: 1px 2px; + border-radius: 2px; + background: #ffe08a; + color: inherit; +} + +.site-search-footer { + color: #777; + font-size: 12px; +} + +.site-search-footer span + span { + margin-left: 12px; +} + +@media (max-width: 767px) { + #site-search-input { + font-size: 16px; + } + + .site-search-results { + max-height: calc(100vh - 230px); + } + + .site-search-footer { + overflow-x: auto; + white-space: nowrap; + } +} diff --git a/docs/public/assets/js/site.js b/docs/public/assets/js/site.js new file mode 100644 index 0000000000..cfadeb0f26 --- /dev/null +++ b/docs/public/assets/js/site.js @@ -0,0 +1,477 @@ +document.querySelectorAll("[data-toggle='collapse'][data-target]").forEach((toggle) => { + toggle.addEventListener("click", (event) => { + event.preventDefault() + + const targetSelector = toggle.getAttribute("data-target") + if (!targetSelector) { + return + } + + document.querySelectorAll(targetSelector).forEach((target) => { + target.classList.toggle("in") + }) + }) +}) + +document.querySelector("[data-docs-toc-toggle]")?.addEventListener("click", () => { + const toc = document.querySelector(".toc") + if (!toc) { + return + } + + toc.classList.toggle("visible-toc") + toc.classList.toggle("hidden-toc") +}) + +const searchModal = document.getElementById("site-search-modal") +if (searchModal) { + initializeSiteSearch(searchModal) +} + +function initializeSiteSearch(modal) { + const input = modal.querySelector("#site-search-input") + const clearButton = modal.querySelector("#site-search-clear") + const form = modal.querySelector("#site-search-form") + const resultsList = modal.querySelector("#site-search-results") + const status = modal.querySelector("#site-search-status") + + if ( + !(input instanceof HTMLInputElement) || + !(clearButton instanceof HTMLButtonElement) || + !(form instanceof HTMLFormElement) || + !(resultsList instanceof HTMLOListElement) || + !(status instanceof HTMLElement) + ) { + return + } + + let activeIndex = -1 + let activeSearchId = 0 + let debounceTimer = 0 + let lastActiveElement = null + let searchIndexPromise = null + let visibleResults = [] + let visibleResultsQuery = "" + + document.querySelectorAll("[data-site-search-open]").forEach((trigger) => { + trigger.addEventListener("click", (event) => { + event.preventDefault() + openSearch("", trigger) + }) + }) + + document.querySelectorAll("[data-site-search-form]").forEach((searchForm) => { + searchForm.addEventListener("submit", (event) => { + event.preventDefault() + const queryInput = searchForm.querySelector("[data-site-search-query]") + const query = queryInput instanceof HTMLInputElement ? queryInput.value : "" + openSearch(query, searchForm) + if (queryInput instanceof HTMLInputElement) { + queryInput.value = "" + } + }) + }) + + document.addEventListener("keydown", (event) => { + if (event.defaultPrevented || isTypingTarget(event.target)) { + return + } + + const key = event.key.toLowerCase() + if ((key === "k" && (event.ctrlKey || event.metaKey)) || key === "/") { + event.preventDefault() + openSearch("", document.activeElement) + } + }) + + modal.addEventListener("keydown", (event) => { + if (event.key === "Escape") { + event.preventDefault() + closeSearch() + return + } + + if (event.key === "Tab") { + trapFocus(event) + return + } + + if (event.key === "ArrowDown") { + event.preventDefault() + setActiveResult(Math.min(activeIndex + 1, visibleResults.length - 1)) + return + } + + if (event.key === "ArrowUp") { + event.preventDefault() + setActiveResult(Math.max(activeIndex - 1, 0)) + } + }) + + modal.addEventListener("click", (event) => { + if (event.target instanceof Element && event.target.closest("[data-site-search-close]")) { + closeSearch() + } + }) + + form.addEventListener("submit", (event) => { + event.preventDefault() + const currentQuery = input.value.trim() + if (!currentQuery) { + clearResults() + return + } + + if (visibleResultsQuery !== currentQuery) { + window.clearTimeout(debounceTimer) + void performSearch(currentQuery) + return + } + + const activeResult = visibleResults[activeIndex] + if (activeResult) { + window.location.href = activeResult.url + } + }) + + input.addEventListener("input", () => { + window.clearTimeout(debounceTimer) + const query = input.value.trim() + if (!query) { + clearResults() + return + } + + resetResults(`Searching for "${query}"...`, false) + debounceTimer = window.setTimeout(() => performSearch(input.value), 120) + }) + + clearButton.addEventListener("click", () => { + window.clearTimeout(debounceTimer) + input.value = "" + input.focus() + clearResults() + }) + + resultsList.addEventListener("mousemove", (event) => { + const item = event.target instanceof Element ? event.target.closest("[data-site-search-result-index]") : null + if (!(item instanceof HTMLElement)) { + return + } + + setActiveResult(Number(item.dataset.siteSearchResultIndex)) + }) + + function openSearch(query, sourceElement) { + lastActiveElement = sourceElement instanceof HTMLElement ? sourceElement : document.activeElement + modal.hidden = false + document.body.classList.add("site-search-open") + + const trimmedQuery = query.trim() + if (trimmedQuery) { + input.value = query + resetResults(`Searching for "${trimmedQuery}"...`, false) + void performSearch(query) + } else if (!input.value.trim()) { + clearResults() + } + + window.requestAnimationFrame(() => { + input.focus() + input.select() + }) + } + + function closeSearch() { + modal.hidden = true + document.body.classList.remove("site-search-open") + if (lastActiveElement instanceof HTMLElement) { + lastActiveElement.focus() + } + } + + async function performSearch(query) { + const searchId = ++activeSearchId + const trimmedQuery = query.trim() + clearButton.hidden = !trimmedQuery + + if (!trimmedQuery) { + clearResults() + return + } + + setStatus(`Searching for "${trimmedQuery}"...`) + + try { + const entries = await loadSearchIndex() + if (searchId !== activeSearchId) { + return + } + + const matches = searchEntries(entries, trimmedQuery) + visibleResults = matches.slice(0, 30) + renderResults(trimmedQuery, matches.length) + } catch (error) { + if (searchId !== activeSearchId) { + return + } + + console.error(error) + visibleResults = [] + visibleResultsQuery = "" + resultsList.replaceChildren() + setStatus("Search is unavailable. Please try again.") + return + } + } + + async function loadSearchIndex() { + if (!searchIndexPromise) { + searchIndexPromise = fetch("/search-index.json", { headers: { accept: "application/json" } }) + .then((response) => { + if (!response.ok) { + throw new Error(`Search index request failed with ${response.status}`) + } + + return response.json() + }) + .then((data) => Array.isArray(data.entries) ? data.entries : []) + } + + return searchIndexPromise + } + + function renderResults(query, totalCount) { + visibleResultsQuery = query.trim() + resultsList.replaceChildren(...visibleResults.map((result, index) => renderResult(result, index, query))) + setActiveResult(visibleResults.length ? 0 : -1) + + if (!visibleResults.length) { + setStatus(`No results found for "${query}".`) + return + } + + if (totalCount > visibleResults.length) { + setStatus(`Top ${visibleResults.length} of ${totalCount} results for "${query}".`) + return + } + + setStatus(`${visibleResults.length} ${visibleResults.length === 1 ? "result" : "results"} for "${query}".`) + } + + function renderResult(result, index, query) { + const item = document.createElement("li") + item.className = "site-search-result" + item.dataset.siteSearchResultIndex = String(index) + + const link = document.createElement("a") + link.className = "site-search-result-title" + link.href = result.url + appendHighlightedText(link, result.title, query) + item.append(link) + + const path = document.createElement("p") + path.className = "site-search-result-url" + path.textContent = result.url + item.append(path) + + const excerpt = document.createElement("p") + excerpt.className = "site-search-result-excerpt" + appendHighlightedText(excerpt, result.excerpt || result.description || result.text, query) + item.append(excerpt) + + return item + } + + function setActiveResult(index) { + activeIndex = Number.isFinite(index) ? index : -1 + resultsList.querySelectorAll("[data-site-search-result-index]").forEach((item) => { + const itemIndex = Number(item.dataset.siteSearchResultIndex) + item.classList.toggle("is-active", itemIndex === activeIndex) + if (itemIndex === activeIndex) { + item.scrollIntoView({ block: "nearest" }) + } + }) + } + + function clearResults() { + resetResults("Start typing to search.", true) + } + + function resetResults(message, hideClearButton) { + activeSearchId++ + visibleResults = [] + visibleResultsQuery = "" + activeIndex = -1 + clearButton.hidden = hideClearButton + resultsList.replaceChildren() + setStatus(message) + } + + function setStatus(message) { + status.textContent = message + } + + function trapFocus(event) { + const focusable = focusableSearchElements() + if (!focusable.length) { + event.preventDefault() + input.focus() + return + } + + const first = focusable[0] + const last = focusable[focusable.length - 1] + const activeElement = document.activeElement + + if (event.shiftKey) { + if (activeElement === first || !modal.contains(activeElement)) { + event.preventDefault() + last.focus() + } + return + } + + if (activeElement === last) { + event.preventDefault() + first.focus() + } + } + + function focusableSearchElements() { + return [...modal.querySelectorAll("a[href], button, input, select, textarea, [tabindex]:not([tabindex='-1'])")] + .filter((element) => { + return element instanceof HTMLElement && + !element.hasAttribute("disabled") && + !element.hasAttribute("hidden") && + (element.offsetParent !== null || element === document.activeElement) + }) + } +} + +function searchEntries(entries, query) { + const tokens = tokenize(query) + if (!tokens.length) { + return [] + } + + const phrase = normalizeSearchText(query) + return entries + .map((entry) => { + const score = scoreSearchEntry(entry, tokens, phrase) + return score > 0 ? { ...entry, excerpt: excerptFor(entry, tokens), score } : null + }) + .filter(Boolean) + .sort((a, b) => b.score - a.score || a.title.localeCompare(b.title)) +} + +function scoreSearchEntry(entry, tokens, phrase) { + const title = normalizeSearchText(entry.title) + const description = normalizeSearchText(entry.description) + const text = normalizeSearchText(entry.text) + const url = normalizeSearchText(entry.url) + const haystack = `${title} ${description} ${text} ${url}` + + if (!tokens.every((token) => haystack.includes(token))) { + return 0 + } + + let score = 0 + if (title === phrase) { + score += 100 + } else if (title.includes(phrase)) { + score += 70 + } + + if (url.includes(phrase)) { + score += 30 + } + + if (entry.url?.startsWith("/docs/")) { + score += 18 + } + + for (const token of tokens) { + if (title.split(/\s+/).includes(token)) { + score += 32 + } else if (title.includes(token)) { + score += 24 + } + + if (description.includes(token)) { + score += 10 + } + + if (url.includes(token)) { + score += 8 + } + + if (text.includes(token)) { + score += 3 + } + } + + return score +} + +function excerptFor(entry, tokens) { + const source = [entry.text, entry.description] + .filter(Boolean) + .find((value) => { + const normalized = normalizeSearchText(value) + return tokens.some((token) => normalized.includes(token)) + }) || entry.description || entry.text || "" + const normalized = normalizeSearchText(source) + const firstMatch = tokens + .map((token) => normalized.indexOf(token)) + .filter((index) => index >= 0) + .sort((a, b) => a - b)[0] ?? 0 + + const start = Math.max(0, firstMatch - 90) + const end = Math.min(source.length, firstMatch + 180) + const prefix = start > 0 ? "... " : "" + const suffix = end < source.length ? " ..." : "" + return `${prefix}${source.slice(start, end).trim()}${suffix}` +} + +function appendHighlightedText(parent, text, query) { + const tokens = tokenize(query) + if (!tokens.length) { + parent.textContent = text + return + } + + const pattern = new RegExp(`(${tokens.map(escapeRegExp).join("|")})`, "gi") + for (const part of text.split(pattern)) { + if (!part) { + continue + } + + if (tokens.includes(part.toLowerCase())) { + const mark = document.createElement("mark") + mark.textContent = part + parent.append(mark) + } else { + parent.append(document.createTextNode(part)) + } + } +} + +function tokenize(value) { + return [...new Set(normalizeSearchText(value).match(/[a-z0-9#.+-]+/g) ?? [])] +} + +function normalizeSearchText(value) { + return String(value ?? "").toLowerCase() +} + +function escapeRegExp(value) { + return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") +} + +function isTypingTarget(target) { + return target instanceof HTMLInputElement || + target instanceof HTMLTextAreaElement || + target instanceof HTMLSelectElement || + (target instanceof HTMLElement && target.isContentEditable) +} diff --git a/docs/scripts/browser/exceptionless-client.ts b/docs/scripts/browser/exceptionless-client.ts new file mode 100644 index 0000000000..61cc7727a1 --- /dev/null +++ b/docs/scripts/browser/exceptionless-client.ts @@ -0,0 +1,29 @@ +import { Exceptionless } from "@exceptionless/browser" + +const options = new URL(import.meta.url).searchParams +const apiKey = options.get("apiKey") + +if (apiKey) { + await Exceptionless.startup((clientConfig) => { + clientConfig.apiKey = apiKey + clientConfig.defaultTags.push("Website") + + const serverUrl = options.get("serverUrl") + if (serverUrl) { + clientConfig.serverUrl = serverUrl + } + + const version = options.get("version") + if (version) { + clientConfig.version = version + } + + clientConfig.useSessions() + clientConfig.addPlugin("site-context", 10, async (context) => { + context.event.data = context.event.data || {} + context.event.data["@page"] = location.pathname + context.event.data["@page.url"] = location.href + context.event.data["@page.title"] = document.title + }) + }) +} diff --git a/docs/scripts/postbuild.ts b/docs/scripts/postbuild.ts index bc91d94732..99d2f00ad0 100644 --- a/docs/scripts/postbuild.ts +++ b/docs/scripts/postbuild.ts @@ -15,8 +15,21 @@ type RedirectAlias = { to: string } +type SearchIndexEntry = { + title: string + url: string + description: string + text: string +} + +type SiteData = { + description?: string +} + const siteUrl = "https://exceptionless.com" const newsPostsPerPage = 10 +const siteData = JSON.parse(await Deno.readTextFile("_data/site.json")) as SiteData +const fallbackDescription = normalizeHtmlText(siteData.description ?? "") const generated = JSON.parse(await Deno.readTextFile("_site/site-data.json")) as GeneratedData await copyDir("public", "_site") @@ -26,6 +39,7 @@ await rewriteHtmlReferences("_site") await rewriteNewsIndex(generated.newsPosts) const routes = await collectHtmlRoutes("_site") +await writeSearchIndex("_site", routes) const aliases = await collectRedirectAliases("_site", generated.newsPosts) await createRedirectAliasPages(aliases) @@ -145,11 +159,14 @@ function removeDuplicatePostHeading(html: string): string { function normalizeHtmlText(html: string): string { return html .replace(/<[^>]*>/g, "") + .replace(/ /g, " ") .replace(/&/g, "&") .replace(/"/g, '"') .replace(/'|'/g, "'") .replace(/</g, "<") .replace(/>/g, ">") + .replace(/&#(\d+);/g, (_match, value: string) => String.fromCodePoint(Number(value))) + .replace(/&#x([0-9a-f]+);/gi, (_match, value: string) => String.fromCodePoint(parseInt(value, 16))) .replace(/\s+/g, " ") .trim() } @@ -302,6 +319,114 @@ async function collectHtmlRoutes(root: string): Promise { return [...new Set(routes)].sort() } +async function writeSearchIndex(root: string, routes: string[]): Promise { + const entries: SearchIndexEntry[] = [] + + for (const route of routes) { + if (!shouldIndexRoute(route)) { + continue + } + + const htmlPath = htmlPathForRoute(root, route) + let html: string + try { + html = await Deno.readTextFile(htmlPath) + } catch { + continue + } + + const cleanedHtml = stripSearchIgnoredContent(stripHtmlComments(html)) + const mainHtml = extractMainHtml(cleanedHtml) || cleanedHtml + const text = htmlToText(mainHtml) + if (!text) { + continue + } + + entries.push({ + title: pageTitle(cleanedHtml) || titleFromRoute(route), + url: route, + description: pageDescription(cleanedHtml), + text, + }) + } + + await Deno.writeTextFile(`${root}/search-index.json`, JSON.stringify({ entries }, null, 2)) +} + +function shouldIndexRoute(route: string): boolean { + return route !== "/404.html" && + route !== "/search/" && + route !== "/news/" && + !route.startsWith("/news/page/") && + !route.startsWith("/category/") +} + +function htmlPathForRoute(root: string, route: string): string { + if (route === "/404.html") { + return `${root}/404.html` + } + + const relative = route.replace(/^\/+/, "") + if (!relative) { + return `${root}/index.html` + } + + return route.endsWith("/") ? `${root}/${relative}index.html` : `${root}/${relative}` +} + +function stripSearchIgnoredContent(html: string): string { + let previous = "" + let current = html + while (current !== previous) { + previous = current + current = current.replace(/<([a-z][\w:-]*)(?=[^>]*\bdata-search-ignore\b)[^>]*>[\s\S]*?<\/\1>/gi, "") + } + + return current.replace(/<[^>]*\bdata-search-ignore\b[^>]*>/gi, "") +} + +function extractMainHtml(html: string): string { + return html.match(/]*id=["']page-content["'][^>]*>([\s\S]*?)<\/main>/i)?.[1] ?? "" +} + +function pageTitle(html: string): string { + const title = html.match(/]*>([\s\S]*?)<\/title>/i)?.[1] ?? "" + return htmlToText(title).replace(/\s+-\s+Exceptionless$/, "").trim() +} + +function metaDescription(html: string): string { + return htmlToText( + html.match(/]*content=["']([^"']*)["'][^>]*>/i)?.[1] ?? + html.match(/]*name=["']description["'][^>]*>/i)?.[1] ?? + "", + ) +} + +function pageDescription(html: string): string { + const description = metaDescription(html) + return description && description !== fallbackDescription ? description : "" +} + +function titleFromRoute(route: string): string { + const segment = route.replace(/\/$/, "").split("/").filter(Boolean).at(-1) || "Exceptionless" + return segment + .split("-") + .map((part) => part ? part[0].toUpperCase() + part.slice(1) : part) + .join(" ") +} + +function htmlToText(html: string): string { + return normalizeHtmlText( + html + .replace(//gi, " ") + .replace(//gi, " ") + .replace( + /<\/?(?:article|aside|blockquote|br|dd|div|dl|dt|figcaption|figure|footer|h[1-6]|header|li|main|nav|ol|p|pre|section|table|td|th|tr|ul)\b[^>]*>/gi, + " ", + ), + ) +} + async function collectRedirectAliases(root: string, posts: ContentPage[]): Promise { const aliases = new Map() const postAliases = buildPostAliasMap(posts) diff --git a/docs/scripts/serve.ts b/docs/scripts/serve.ts index fe2e96fc17..1ec510beba 100644 --- a/docs/scripts/serve.ts +++ b/docs/scripts/serve.ts @@ -1,7 +1,7 @@ const root = new URL("../_site/", import.meta.url) -const port = getPort(Deno.args) +const port = getPort(Deno.args, Deno.env.get("PORT")) -Deno.serve({ hostname: "localhost", port }, async (request) => { +Deno.serve({ hostname: "127.0.0.1", port }, async (request) => { const requestUrl = new URL(request.url) const fileUrl = resolveFileUrl(requestUrl.pathname) @@ -11,6 +11,7 @@ Deno.serve({ hostname: "localhost", port }, async (request) => { "application/octet-stream" return new Response(file.readable, { headers: { + "cache-control": "no-store", "content-type": contentType, }, }) @@ -20,6 +21,7 @@ Deno.serve({ hostname: "localhost", port }, async (request) => { return new Response(await Deno.readTextFile(notFound), { status: 404, headers: { + "cache-control": "no-store", "content-type": "text/html; charset=utf-8", }, }) @@ -29,19 +31,25 @@ Deno.serve({ hostname: "localhost", port }, async (request) => { } }) -function getPort(args: string[]): number { +function getPort(args: string[], environmentPort?: string): number { const portIndex = args.indexOf("--port") if (portIndex >= 0) { - const value = args[portIndex + 1] - if (value) { - const parsed = Number(value) - if (Number.isInteger(parsed) && parsed > 0 && parsed <= 65535) { - return parsed - } + const port = parsePort(args[portIndex + 1]) + if (port) { + return port } } - return 3000 + return parsePort(environmentPort) ?? 3000 +} + +function parsePort(value?: string): number | undefined { + if (!value) { + return undefined + } + + const parsed = Number(value) + return Number.isInteger(parsed) && parsed > 0 && parsed <= 65535 ? parsed : undefined } function resolveFileUrl(pathname: string): URL { diff --git a/docs/search.md b/docs/search.md deleted file mode 100644 index 6619c655b1..0000000000 --- a/docs/search.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Search Results -url: /search/ -layout: layouts/docs.vto ---- - -# Search Results - -
    diff --git a/docs/site-migration-plan.md b/docs/site-migration-plan.md index 49e2d9eed6..4268a24d98 100644 --- a/docs/site-migration-plan.md +++ b/docs/site-migration-plan.md @@ -66,7 +66,7 @@ docs/ index.vto # news index route public/ # static assets copied to output scripts/ - site-collections.ts # normalizes Lume search page data into docs/news collections + site-collections.ts # normalizes Lume page data into docs/news collections postbuild.ts # copies assets, rewrites refs, writes feeds/sitemap/LLMS serve.ts # serves final _site output with clean URLs verify-links.ts # verifies generated local links, anchors, CSS URLs, srcset, and assets @@ -85,18 +85,20 @@ Run commands from `docs/`. { "tasks": { "lume": "deno run -P=lume lume/cli.ts", - "build": "deno task lume && deno task postbuild", - "serve": "deno task build && deno run --allow-read=_site --allow-net=localhost,127.0.0.1 scripts/serve.ts", + "build": "deno task lume && deno task postbuild && deno bundle --platform=browser --minify --config=deno.json scripts/browser/exceptionless-client.ts -o _site/assets/js/exceptionless-client.js", + "serve": "deno task build && deno run --allow-read=_site --allow-net=localhost,127.0.0.1 --allow-env=PORT scripts/serve.ts", "postbuild": "deno run --allow-read --allow-write scripts/postbuild.ts", - "check": "deno check _config.ts scripts/site-collections.ts scripts/postbuild.ts scripts/serve.ts scripts/verify-links.ts", - "verify": "deno task build && deno run --allow-read scripts/verify-links.ts" + "check": "deno check _config.ts scripts/browser/exceptionless-client.ts scripts/site-collections.ts scripts/postbuild.ts scripts/serve.ts scripts/verify-links.ts scripts/find-unused.ts", + "verify": "deno task build && deno run --allow-read scripts/verify-links.ts", + "unused": "deno task build && deno run --allow-read scripts/find-unused.ts" } } ``` `serve` intentionally builds first and then serves `_site`, so local QA uses the same postbuild output that would be -deployed. Do not use a long-running serve command for normal static checks; use `deno task build`, `deno task check`, -and `deno task verify` first. +deployed. It accepts `--port` and the `PORT` environment variable for Codex/Aspire integration. Do not use a +long-running serve command for normal static checks; use `deno task build`, `deno task check`, and `deno task verify` +first. ## Lume Configuration @@ -228,6 +230,51 @@ because each composition is used once. Shared site chrome stays in `layouts/base Create a reusable component only when it is genuinely reused by multiple pages or removes meaningful duplication. Do not create a fragment just to move a single route's HTML elsewhere. +## Site Search + +Search is backed by a generated `/search-index.json` file and a base-layout modal. There is no dedicated search page. +The normal docs build renders the Lume site, then `postbuild.ts` indexes final rendered HTML before redirect alias pages +are generated. + +Commands: + +- `deno task build` builds the site and generates `/search-index.json`. +- `deno task build` also bundles the static-site Exceptionless browser bootstrap from the Deno npm dependency. +- The Codex environment exposes a `Run Lume Docs` action on port 7141. +- The Aspire AppHost exposes a `Docs` resource at `http://localhost:7141` unless a scoped worktree assigns an ephemeral + free port. + +Search implementation notes: + +- `postbuild.ts` indexes rendered HTML routes and skips `/404.html`, `/news/`, paged news indexes, category pages, and + the removed `/search/` route. +- The docs layout's generic `Documentation` page heading, responsive table-of-contents control, and sidebar navigation + use `data-search-ignore` so results use the actual content page title and article text. +- `public/assets/js/site.js` lazy-loads `/search-index.json`, opens the search modal from the header, keyboard shortcut, + or docs sidebar form, and supports debounced input, excerpts, highlight marks, clear, and keyboard selection. +- The docs sidebar search form opens the modal with the entered query. It does not navigate to `/search/?q=...`. +- The docs site uses the migrated Bootstrap-era theme CSS, not Tailwind. Keep search-specific CSS limited to modal and + result presentation that the legacy theme does not already provide. + +## Static Site Error Reporting + +The migrated static site can load a small Exceptionless browser-client bootstrap at `/assets/js/exceptionless-client.js`. +`deno task build` bundles this file from `scripts/browser/exceptionless-client.ts` and the Deno npm dependency +`@exceptionless/browser@3.2.1`; it does not import the browser client from a runtime CDN. The layout emits this script +only when configured with a public browser API key at build time. + +Build-time configuration: + +- `EXCEPTIONLESS_SITE_API_KEY` +- `EXCEPTIONLESS_SITE_SERVER_URL` +- `EXCEPTIONLESS_SITE_VERSION` + +Google Tag Manager is part of the public site layout and loads by default. Local Codex and Aspire docs runs do not force +any Exceptionless configuration; the browser client script is not emitted unless an API key is supplied. + +Use a client-safe public API key and do not use a privileged server key. The Svelte app has its own +`@exceptionless/browser` startup path in `src/Exceptionless.Web/ClientApp/src/hooks.client.ts`. + ## Build Pipeline `deno task build` does this automatically: @@ -242,7 +289,8 @@ create a fragment just to move a single route's HTML elsewhere. 8. `postbuild.ts` generates `feed.xml` from news Markdown. 9. `postbuild.ts` generates `sitemap.xml` from rendered routes. 10. `postbuild.ts` generates docs-only `llms.txt` and `llms-full.txt`. -11. `postbuild.ts` generates redirect aliases for legacy links. +11. `postbuild.ts` writes `/search-index.json` from rendered HTML routes. +12. `postbuild.ts` generates redirect aliases for legacy links. ## Verification Gates @@ -284,11 +332,21 @@ Implementation notes from the verification pass: - Markdown headings receive deterministic legacy-style IDs during Lume Markdown rendering so existing same-page anchors continue to work. - `docs/docs/demo-formatting.md` is `url: false` and is intentionally not published. -- `/search/` exists as a migrated route so sitemap parity remains exact. +- Site search uses `/search-index.json` and the base-layout modal instead of publishing a placeholder `/search/` page. - `postbuild.ts` contains the small migration normalizers required for parity: migrated image-reference rewrites, duplicate news H1 removal, standalone YouTube URL embed rendering, Prism `
    ` class normalization, news index/RSS/sitemap/LLMS generation, internal non-doc link stripping for `llms-full.txt`, and redirect alias generation.
 - The legacy Fancybox stylesheet references `/assets/images/fancybox.png` and `/assets/images/fancybox-x.png`; both are committed static assets.
 - Fancybox uses the original 1.3.4 plugin plus a tiny jQuery 1.9 browser-compat shim because the WordPress-patched Easy FancyBox script requires `DOMPurify`.
 - A mobile footer override removes the legacy 20px horizontal overflow caused by the old negative-margin footer rule.
+
+## Verified Search Upgrade - 2026-07-08
+
+- Search is generated by `postbuild.ts` as `/search-index.json`; no Pagefind task, package, worker, or `/search/` page
+  is required.
+- The header search button, Ctrl/Command+K, `/`, and the docs sidebar search form all open the same modal.
+- The modal lazy-loads the JSON index, returns ranked results with excerpts and highlights, supports clear, Enter,
+  Escape, and Up/Down keyboard behavior, and leaves the current page URL unchanged.
+- The index skips redirect aliases and repeated docs navigation chrome.
+
 ## Core Principle
 
 The maintained source should be Markdown, metadata, shared Vento layouts, route-level Vento pages where needed, and
diff --git a/src/Exceptionless.AppHost/Exceptionless.AppHost.csproj b/src/Exceptionless.AppHost/Exceptionless.AppHost.csproj
index b5760cb90e..4e742afed7 100644
--- a/src/Exceptionless.AppHost/Exceptionless.AppHost.csproj
+++ b/src/Exceptionless.AppHost/Exceptionless.AppHost.csproj
@@ -13,6 +13,7 @@
     
     
     
+    
     
   
 
diff --git a/src/Exceptionless.AppHost/Extensions/WorktreeScope.cs b/src/Exceptionless.AppHost/Extensions/WorktreeScope.cs
index 3d52557703..c86241f691 100644
--- a/src/Exceptionless.AppHost/Extensions/WorktreeScope.cs
+++ b/src/Exceptionless.AppHost/Extensions/WorktreeScope.cs
@@ -13,7 +13,8 @@ public sealed record WorktreePorts(
     int OldAppHttp,
     int OldAppHttps,
     int OldAppLiveReload,
-    int AppHttps)
+    int AppHttps,
+    int DocsHttp)
 {
     public string ApiHttpUrl => $"http://localhost:{ApiHttp}";
     public string ApiHttpsUrl => $"https://localhost:{ApiHttps}";
@@ -49,7 +50,7 @@ public static class WorktreeScope
 
     public static WorktreePorts AssignFreePorts()
     {
-        int[] ports = FreePorts(11);
+        int[] ports = FreePorts(12);
         var assignments = new WorktreePorts(
             ports[0],
             ports[1],
@@ -61,7 +62,8 @@ public static WorktreePorts AssignFreePorts()
             ports[7],
             ports[8],
             ports[9],
-            ports[10]);
+            ports[10],
+            ports[11]);
 
         Environment.SetEnvironmentVariable("ASPNETCORE_URLS", $"https://localhost:{assignments.DashboardHttps};http://localhost:{assignments.DashboardHttp}");
         Environment.SetEnvironmentVariable("DOTNET_DASHBOARD_OTLP_ENDPOINT_URL", $"https://localhost:{assignments.DashboardOtlp}");
diff --git a/src/Exceptionless.AppHost/Program.cs b/src/Exceptionless.AppHost/Program.cs
index 59003cfe45..a2db8d0d36 100644
--- a/src/Exceptionless.AppHost/Program.cs
+++ b/src/Exceptionless.AppHost/Program.cs
@@ -14,6 +14,7 @@
 int oldAppLiveReloadPort = worktreePorts?.OldAppLiveReload ?? 35729;
 string oldAppAspNetCoreUrls = String.Concat("http://localhost:", oldAppHttpPort);
 int appPort = worktreePorts?.AppHttps ?? 7131;
+int docsPort = worktreePorts?.DocsHttp ?? 7141;
 const int DefaultApiHttpsPort = 7111;
 string exceptionlessServerUrl = worktreePorts?.ApiHttpsUrl ?? $"https://api-ex.dev.localhost:{DefaultApiHttpsPort}";
 const string SharedEmailConnectionString = "smtp://localhost:1025";
@@ -206,6 +207,24 @@
             .WithEnvironment("OLDAPP_HTTP", worktreePorts.OldAppHttpsUrl)
             .WithEnvironment("OLDAPP_HTTPS", worktreePorts.OldAppHttpsUrl);
     }
+
+    if (includeDevTools)
+    {
+        builder.AddDenoTask("Docs", "../../docs", "serve")
+            .WithBrowserLogs()
+            .WithHttpEndpoint(port: docsPort, targetPort: docsPort, name: "http", env: "PORT", isProxied: false)
+            .WithEndpoint("http", e =>
+            {
+                e.TargetHost = "localhost";
+                e.UriScheme = "http";
+            })
+            .WithUrlForEndpoint("http", u =>
+            {
+                u.DisplayText = "Open Docs";
+                u.DisplayOrder = 100;
+            })
+            .WithParentRelationship(api);
+    }
 #pragma warning restore ASPIREBROWSERLOGS001
 }
 
diff --git a/src/Exceptionless.Web/ClientApp/.npmrc b/src/Exceptionless.Web/ClientApp/.npmrc
index d13caea8ee..024ce18404 100644
--- a/src/Exceptionless.Web/ClientApp/.npmrc
+++ b/src/Exceptionless.Web/ClientApp/.npmrc
@@ -1,2 +1,2 @@
 engine-strict=true
-min-release-age=7
+min-release-age=3