From 56abf82472caca842b0493af24a40e4ec6a728e7 Mon Sep 17 00:00:00 2001 From: Blake Niemyjski Date: Tue, 7 Jul 2026 15:19:32 -0500 Subject: [PATCH 01/10] Add local Lume docs run support --- .codex/environments/environment.toml | 26 ++- docs/_config.ts | 49 ++++ docs/_includes/layouts/base.vto | 21 +- docs/_includes/layouts/docs.vto | 32 +-- docs/deno.json | 9 +- docs/deno.lock | 49 ++++ docs/public/assets/css/search.css | 71 ++++++ docs/public/assets/js/docs-layout.js | 9 + docs/public/assets/js/search.js | 219 ++++++++++++++++++ docs/public/assets/js/site.js | 14 ++ docs/scripts/browser/exceptionless-client.ts | 35 +++ docs/scripts/postbuild.ts | 2 +- docs/scripts/serve.ts | 26 ++- docs/search.md | 28 ++- docs/site-migration-plan.md | 79 ++++++- .../Extensions/WorktreeScope.cs | 8 +- src/Exceptionless.AppHost/Program.cs | 18 ++ 17 files changed, 632 insertions(+), 63 deletions(-) create mode 100644 docs/public/assets/css/search.css create mode 100644 docs/public/assets/js/docs-layout.js create mode 100644 docs/public/assets/js/search.js create mode 100644 docs/public/assets/js/site.js create mode 100644 docs/scripts/browser/exceptionless-client.ts diff --git a/.codex/environments/environment.toml b/.codex/environments/environment.toml index df9fe419ab..063467dc65 100644 --- a/.codex/environments/environment.toml +++ b/.codex/environments/environment.toml @@ -25,6 +25,11 @@ if ! command -v npm >/dev/null 2>&1; then exit 1 fi +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 "dotnet:" dotnet --version @@ -34,6 +39,9 @@ node --version echo "npm:" npm --version +echo "deno:" +deno --version + echo "Restoring .NET workloads..." dotnet workload restore @@ -46,7 +54,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 +70,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 {} + @@ -88,6 +98,20 @@ else 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}" + +echo "Starting Lume docs at http://127.0.0.1:$PORT/" +deno task serve -- --port "$PORT" +''' + [[actions]] name = "Stop Aspire Containers, keep data" icon = "tool" diff --git a/docs/_config.ts b/docs/_config.ts index d31c755189..3c908ae826 100644 --- a/docs/_config.ts +++ b/docs/_config.ts @@ -63,9 +63,58 @@ 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 = firstNonEmpty( + Deno.env.get("EXCEPTIONLESS_SITE_API_KEY"), + Deno.env.get("PUBLIC_EXCEPTIONLESS_API_KEY"), + ) + if (!apiKey) { + return "" + } + + const params = new URLSearchParams({ apiKey }) + const serverUrl = firstNonEmpty( + Deno.env.get("EXCEPTIONLESS_SITE_SERVER_URL"), + Deno.env.get("PUBLIC_EXCEPTIONLESS_SERVER_URL"), + ) + + if (serverUrl) { + params.set("serverUrl", serverUrl) + } + + const environment = firstNonEmpty( + Deno.env.get("EXCEPTIONLESS_SITE_ENVIRONMENT"), + Deno.env.get("EX_AppMode"), + ) + if (isNonProduction(environment)) { + params.set("environment", environment) + } + + const version = firstNonEmpty( + Deno.env.get("EXCEPTIONLESS_SITE_VERSION"), + Deno.env.get("PUBLIC_APP_VERSION"), + Deno.env.get("GITHUB_SHA"), + ) + if (version) { + params.set("version", version) + } + + return `/assets/js/exceptionless-client.js?${params}` +} + +function isNonProduction(environment: string): boolean { + const normalizedEnvironment = environment.trim().toLowerCase() + return normalizedEnvironment !== "" && normalizedEnvironment !== "production" && normalizedEnvironment !== "prod" +} + +function firstNonEmpty(...values: Array): string { + return values.find((value) => value && value.trim())?.trim() ?? "" +} + 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..c73d5dfc16 100644 --- a/docs/_includes/layouts/base.vto +++ b/docs/_includes/layouts/base.vto @@ -74,7 +74,9 @@ - {{ 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..fde317816e 100644 --- a/docs/_includes/layouts/docs.vto +++ b/docs/_includes/layouts/docs.vto @@ -2,19 +2,21 @@ layout: layouts/base.vto extraStyles: - /assets/css/prism.css +extraModuleScripts: + - /assets/js/docs-layout.js --- -
+

Documentation

-
+
-
- - -
+
+ + +
{{ docsNavHtml(search, url) }}
@@ -22,21 +24,3 @@ extraStyles:
- - diff --git a/docs/deno.json b/docs/deno.json index 720bedd653..7ea0df7565 100644 --- a/docs/deno.json +++ b/docs/deno.json @@ -1,14 +1,17 @@ { "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 task bundle:client && deno task pagefind", + "bundle:client": "deno bundle --platform=browser --minify --config=deno.json scripts/browser/exceptionless-client.ts -o _site/assets/js/exceptionless-client.js", + "pagefind": "npx -y pagefind@1.5.2 --site _site", + "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/search.css b/docs/public/assets/css/search.css new file mode 100644 index 0000000000..a40004c403 --- /dev/null +++ b/docs/public/assets/css/search.css @@ -0,0 +1,71 @@ +.site-search-form { + margin-bottom: 14px; +} + +.site-search-status { + min-height: 22px; + margin-bottom: 18px; +} + +.site-search-result { + padding: 18px 0; + border-top: 1px solid #e5e5e5; +} + +.site-search-result:first-child { + border-top: 0; +} + +.site-search-result-title { + font-size: 20px; + font-weight: 700; + line-height: 1.3; +} + +.site-search-result-url { + margin: 4px 0 8px; + color: #6a8a3a; + font-size: 13px; + word-break: break-word; +} + +.site-search-result-excerpt { + margin: 0; + line-height: 1.55; +} + +.site-search-result-excerpt mark { + padding: 1px 3px; + border-radius: 3px; + background: #ffe08a; + color: inherit; +} + +.site-search-subresults { + margin-top: 10px; +} + +.site-search-actions { + margin-top: 18px; + text-align: center; +} + +.sr-only { + position: absolute; + width: 1px; + height: 1px; + padding: 0; + margin: -1px; + overflow: hidden; + clip: rect(0, 0, 0, 0); + white-space: nowrap; + border: 0; +} + +@media (max-width: 767px) { + .site-search-form input[type="search"], + .site-search-form .btn { + width: 100%; + margin-bottom: 8px; + } +} diff --git a/docs/public/assets/js/docs-layout.js b/docs/public/assets/js/docs-layout.js new file mode 100644 index 0000000000..0b021362cd --- /dev/null +++ b/docs/public/assets/js/docs-layout.js @@ -0,0 +1,9 @@ +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") +}) diff --git a/docs/public/assets/js/search.js b/docs/public/assets/js/search.js new file mode 100644 index 0000000000..f30cb0884c --- /dev/null +++ b/docs/public/assets/js/search.js @@ -0,0 +1,219 @@ +const form = requiredElement("site-search-form", HTMLFormElement) +const input = requiredElement("site-search-input", HTMLInputElement) +const clearButton = requiredElement("site-search-clear", HTMLButtonElement) +const loadMoreButton = requiredElement("site-search-more", HTMLButtonElement) +const resultsList = requiredElement("site-search-results", HTMLOListElement) +const status = requiredElement("site-search-status", HTMLElement) + +const pageSize = 10 +let pagefind +let searchResults = [] +let renderedCount = 0 +let activeSearchId = 0 +let debounceTimer + +const initialQuery = new URLSearchParams(location.search).get("q")?.trim() ?? "" +input.value = initialQuery + +form.addEventListener("submit", (event) => { + event.preventDefault() + runSearch(input.value, { immediate: true, updateUrl: true }) +}) + +input.addEventListener("input", () => { + runSearch(input.value, { updateUrl: true }) +}) + +clearButton.addEventListener("click", () => { + input.value = "" + input.focus() + clearSearch() + updateUrl("") +}) + +loadMoreButton.addEventListener("click", () => { + void renderNextResults(activeSearchId) +}) + +if (initialQuery) { + runSearch(initialQuery, { immediate: true, updateUrl: false }) +} + +function runSearch(query, options = {}) { + clearTimeout(debounceTimer) + const trimmedQuery = query.trim() + + if (!trimmedQuery) { + clearSearch() + updateUrl("") + return + } + + if (options.updateUrl) { + updateUrl(trimmedQuery) + } + + if (options.immediate) { + void performSearch(trimmedQuery) + return + } + + debounceTimer = setTimeout(() => { + void performSearch(trimmedQuery) + }, 250) +} + +async function performSearch(query) { + const searchId = ++activeSearchId + setStatus(`Searching for "${query}"...`) + clearButton.hidden = false + loadMoreButton.hidden = true + resultsList.replaceChildren() + + let response + try { + const api = await loadPagefind() + response = await api.search(query) + } catch (error) { + if (searchId === activeSearchId) { + setStatus("Search is unavailable. Please try again.") + console.error(error) + } + return + } + + if (!response || searchId !== activeSearchId) { + return + } + + searchResults = response.results + renderedCount = 0 + + if (!searchResults.length) { + setStatus(`No results found for "${query}".`) + return + } + + setStatus(`${searchResults.length} ${searchResults.length === 1 ? "result" : "results"} for "${query}".`) + await renderNextResults(searchId) +} + +async function loadPagefind() { + if (pagefind) { + return pagefind + } + + pagefind = await import("/pagefind/pagefind.js") + await pagefind.options({ + excerptLength: 32, + }) + + return pagefind +} + +async function renderNextResults(searchId) { + const nextResults = searchResults.slice(renderedCount, renderedCount + pageSize) + const fragment = document.createDocumentFragment() + + for (const result of nextResults) { + const data = await result.data() + fragment.append(renderResult(data)) + } + + if (searchId !== activeSearchId) { + return + } + + resultsList.append(fragment) + renderedCount += nextResults.length + loadMoreButton.hidden = renderedCount >= searchResults.length +} + +function renderResult(data) { + const item = document.createElement("li") + item.className = "site-search-result" + + const link = document.createElement("a") + link.className = "site-search-result-title" + link.href = data.url + link.textContent = data.meta?.title || titleFromUrl(data.url) + item.append(link) + + const url = document.createElement("p") + url.className = "site-search-result-url" + url.textContent = pathFromUrl(data.url) + item.append(url) + + if (data.excerpt) { + const excerpt = document.createElement("p") + excerpt.className = "site-search-result-excerpt" + excerpt.innerHTML = data.excerpt + item.append(excerpt) + } + + const subResults = data.sub_results?.filter((subResult) => subResult.url !== data.url).slice(0, 3) ?? [] + if (subResults.length) { + const list = document.createElement("ul") + list.className = "site-search-subresults" + + for (const subResult of subResults) { + const subItem = document.createElement("li") + const subLink = document.createElement("a") + subLink.href = subResult.url + subLink.textContent = subResult.title || titleFromUrl(subResult.url) + subItem.append(subLink) + list.append(subItem) + } + + item.append(list) + } + + return item +} + +function clearSearch() { + activeSearchId++ + searchResults = [] + renderedCount = 0 + resultsList.replaceChildren() + clearButton.hidden = true + loadMoreButton.hidden = true + setStatus("Enter a search term to begin.") +} + +function updateUrl(query) { + const url = new URL(location.href) + if (query) { + url.searchParams.set("q", query) + } else { + url.searchParams.delete("q") + } + + history.replaceState({}, "", url) +} + +function setStatus(message) { + status.textContent = message +} + +function pathFromUrl(value) { + return new URL(value, location.origin).pathname +} + +function titleFromUrl(value) { + const path = pathFromUrl(value).replace(/\/$/, "") + const segment = path.split("/").filter(Boolean).pop() || "Exceptionless" + return segment + .split("-") + .map((part) => part ? part[0].toUpperCase() + part.slice(1) : part) + .join(" ") +} + +function requiredElement(id, type) { + const element = document.getElementById(id) + if (element instanceof type) { + return element + } + + throw new Error(`Missing search page element #${id}`) +} diff --git a/docs/public/assets/js/site.js b/docs/public/assets/js/site.js new file mode 100644 index 0000000000..ef35b72ac4 --- /dev/null +++ b/docs/public/assets/js/site.js @@ -0,0 +1,14 @@ +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") + }) + }) +}) diff --git a/docs/scripts/browser/exceptionless-client.ts b/docs/scripts/browser/exceptionless-client.ts new file mode 100644 index 0000000000..763743a5bc --- /dev/null +++ b/docs/scripts/browser/exceptionless-client.ts @@ -0,0 +1,35 @@ +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", "Docs", "Lume") + + const serverUrl = options.get("serverUrl") + if (serverUrl) { + clientConfig.serverUrl = serverUrl + } + + const version = options.get("version") + if (version) { + clientConfig.version = version + } + + const environment = options.get("environment") + if (environment && environment.toLowerCase() !== "production") { + clientConfig.useDebugLogger() + clientConfig.settings["@@log:*"] = "debug" + } + + 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..32e62a348b 100644 --- a/docs/scripts/postbuild.ts +++ b/docs/scripts/postbuild.ts @@ -458,7 +458,7 @@ function renderRedirectPage(target: string): string { Redirecting - Exceptionless - +

Redirecting

diff --git a/docs/scripts/serve.ts b/docs/scripts/serve.ts index fe2e96fc17..68d16ce84f 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) @@ -29,19 +29,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 index 6619c655b1..94c8deca8c 100644 --- a/docs/search.md +++ b/docs/search.md @@ -1,9 +1,31 @@ --- -title: Search Results +title: Search +description: Search Exceptionless documentation, guides, and articles. url: /search/ layout: layouts/docs.vto +robots: noindex,follow +extraStyles: + - /assets/css/search.css +extraModuleScripts: + - /assets/js/search.js --- -# Search Results +
+

Search Exceptionless

+

Find documentation, client guides, release notes, and product pages.

-
+ + +

Enter a search term to begin.

+ +
    + +
    + +
    +
    diff --git a/docs/site-migration-plan.md b/docs/site-migration-plan.md index 49e2d9eed6..1c732d22f6 100644 --- a/docs/site-migration-plan.md +++ b/docs/site-migration-plan.md @@ -85,18 +85,22 @@ 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 task bundle:client && deno task pagefind", + "bundle:client": "deno bundle --platform=browser --minify --config=deno.json scripts/browser/exceptionless-client.ts -o _site/assets/js/exceptionless-client.js", + "pagefind": "npx -y pagefind@1.5.2 --site _site", + "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 +232,52 @@ 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 Pagefind. The normal docs build renders the Lume site, runs `postbuild.ts`, and then generates +the Pagefind index into `_site/pagefind/`. + +Commands: + +- `deno task build` builds the site and generates the Pagefind index. +- `deno task bundle:client` bundles the static-site Exceptionless browser bootstrap from the Deno npm dependency. +- `deno task pagefind` regenerates only the Pagefind index from the current `_site` output. +- 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: + +- The shared base layout marks real page content with `data-pagefind-body` so headers, navigation, and footer content do + not dominate the index. +- Generated redirect alias pages use `data-pagefind-ignore="all"` and should not appear as search results. +- The docs layout's generic `Documentation` page heading is ignored so results use the actual content page title. +- `public/assets/js/search.js` uses Pagefind's browser search API directly for query-string support, debounced input, + result excerpts, sub-results, clear, and load-more behavior. +- The docs sidebar search form navigates to `/search/?q=...`; it is not a table-of-contents-only filter. +- The docs site uses the migrated Bootstrap-era theme CSS, not Tailwind. Keep search-specific CSS limited to 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` or `PUBLIC_EXCEPTIONLESS_API_KEY` +- `EXCEPTIONLESS_SITE_SERVER_URL` or `PUBLIC_EXCEPTIONLESS_SERVER_URL` +- `EXCEPTIONLESS_SITE_ENVIRONMENT` or `EX_AppMode` +- `EXCEPTIONLESS_SITE_VERSION`, `PUBLIC_APP_VERSION`, or `GITHUB_SHA` + +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. + +Do not commit production keys. 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: @@ -243,6 +293,7 @@ create a fragment just to move a single route's HTML elsewhere. 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. +12. Pagefind indexes `_site` into `_site/pagefind/`. ## Verification Gates @@ -284,11 +335,25 @@ 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. +- `/search/` uses Pagefind for local static search while keeping sitemap parity exact. - `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-06
+
+- `deno task check` passed.
+- `deno task build` passed and Pagefind indexed 230 real pages while ignoring 37 redirect alias pages.
+- `deno task verify` passed with no broken local links, anchors, or assets.
+- Local Chrome dogfood at `http://127.0.0.1:7141/search/?q=javascript` returned 114 Pagefind results with
+  `JavaScript Example` first, loaded the local Pagefind script and worker, had no inline scripts, loaded Google Tag
+  Manager from the base layout, did not emit the Exceptionless client script without an API key, and had no console
+  errors, page errors, or failed local resources.
+- Interactive local Chrome dogfood updated the URL to `/search/?q=multiple+queries`, returned 17 results with
+  `Filtering & Searching` first, and cleared back to the empty state.
+- Mobile Chrome dogfood at a 390px viewport returned the same `/search/?q=javascript` results with no horizontal overflow.
+
 ## 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/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..cbbfd5c435 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,23 @@
             .WithEnvironment("OLDAPP_HTTP", worktreePorts.OldAppHttpsUrl)
             .WithEnvironment("OLDAPP_HTTPS", worktreePorts.OldAppHttpsUrl);
     }
+
+    builder.AddJavaScriptApp("Docs", "../../docs", "serve")
+        .WithBrowserLogs()
+        .RemoveJavaScriptDebuggingAnnotation()
+        .WithEnvironment("PORT", docsPort.ToString())
+        .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
 }
 

From f37513eca79924248ecc759e0230465d75d0fc11 Mon Sep 17 00:00:00 2001
From: Blake Niemyjski 
Date: Wed, 8 Jul 2026 19:00:31 -0500
Subject: [PATCH 02/10] Refine docs Pagefind indexing

Use Deno Aspire resource for docs

Polish docs search UI

Use generated modal search for docs

Address docs search review feedback

Cancel docs search debounce on clear

Fix docs search modal button styling

Expose docs search keyboard shortcut

Clarify docs search migration notes

Preserve docs sidebar link color

Align docs search nav on mobile

Fix docs sidebar text color

Restore docs sidebar link color

Match docs sidebar colors to production

Disable caching for local docs server

Use existing nav styling for docs search trigger

Adjust frontend package release age

Reuse theme modal styles for docs search
---
 .codex/environments/environment.toml          |  16 +-
 docs/_includes/layouts/base.vto               |  37 +-
 docs/_includes/layouts/docs.vto               |  12 +-
 docs/deno.json                                |   3 +-
 docs/public/assets/css/custom.css             | 155 +++++++
 docs/public/assets/css/search.css             |  71 ----
 docs/public/assets/js/docs-layout.js          |   9 -
 docs/public/assets/js/search.js               | 219 ----------
 docs/public/assets/js/site.js                 | 393 ++++++++++++++++++
 docs/scripts/postbuild.ts                     | 116 +++++-
 docs/scripts/serve.ts                         |   2 +
 docs/search.md                                |  31 --
 docs/site-migration-plan.md                   |  55 ++-
 .../Exceptionless.AppHost.csproj              |   1 +
 src/Exceptionless.AppHost/Program.cs          |  33 +-
 src/Exceptionless.Web/ClientApp/.npmrc        |   2 +-
 16 files changed, 759 insertions(+), 396 deletions(-)
 delete mode 100644 docs/public/assets/css/search.css
 delete mode 100644 docs/public/assets/js/docs-layout.js
 delete mode 100644 docs/public/assets/js/search.js
 delete mode 100644 docs/search.md

diff --git a/.codex/environments/environment.toml b/.codex/environments/environment.toml
index 063467dc65..dc4815e85b 100644
--- a/.codex/environments/environment.toml
+++ b/.codex/environments/environment.toml
@@ -25,11 +25,6 @@ if ! command -v npm >/dev/null 2>&1; then
   exit 1
 fi
 
-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 "dotnet:"
 dotnet --version
 
@@ -39,9 +34,6 @@ node --version
 echo "npm:"
 npm --version
 
-echo "deno:"
-deno --version
-
 echo "Restoring .NET workloads..."
 dotnet workload restore
 
@@ -108,6 +100,14 @@ 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 -- --port "$PORT"
 '''
diff --git a/docs/_includes/layouts/base.vto b/docs/_includes/layouts/base.vto
index c73d5dfc16..572b5a87c5 100644
--- a/docs/_includes/layouts/base.vto
+++ b/docs/_includes/layouts/base.vto
@@ -63,6 +63,15 @@
           
  1. Pricing
    2. 
           
  2. News
    3. 
           
  3. Docs
    4. 
+          
  4. 
+            Search
+          
    5. 
           
           
         
@@ -74,10 +83,36 @@
    -
    +
    {{ content }}
    + +