fix(search): Update Algolia search to improve content seen and styles in search results

.env

@@ -1,2 +1,2 @@
-VITE_VERSION_LATEST="v11.0.0"
-VITE_VERSION_NEXT="v12.0.0"
+VITE_VERSION_LATEST="v12.0.0"
+VITE_VERSION_NEXT="v13.0.0"

.github/workflows/deploy.yml

@@ -20,8 +20,6 @@ jobs:
       contents: read
       deployments: write
       pull-requests: write
-    outputs:
-      deployment-url: ${{ steps.deploy.outputs.deployment-url }}
     steps:
       - uses: actions/checkout@v6.0.2
       - name: Setup Node.js environment
@@ -54,6 +52,9 @@ jobs:
         run: yarn build
         env:
           VITE_DEPLOYMENT_URL: ${{ env.VITE_DEPLOYMENT_URL }}
+          VITE_ALGOLIA_APP_ID: ${{ secrets.VITE_ALGOLIA_APP_ID }}
+          VITE_ALGOLIA_INDEX_NAME: ${{ secrets.VITE_ALGOLIA_INDEX_NAME }}
+          VITE_ALGOLIA_SEARCH_API_KEY: ${{ secrets.VITE_ALGOLIA_SEARCH_API_KEY }}
       - name: Deploy
         if: ${{ github.actor != 'dependabot[bot]' }}
         id: deploy
@@ -98,10 +99,27 @@ jobs:
         run: yarn install
       - name: Build ReScript
         run: yarn build:res
+      - name: Set Cypress base URL
+        id: cypress-base-url
+        shell: bash
+        run: |
+          RAW_BRANCH="${{ github.head_ref || github.ref_name }}"
+
+          if [[ "$RAW_BRANCH" == "master" ]]; then
+             CYPRESS_BASE_URL="https://rescript-lang.org"
+          else
+             SAFE_BRANCH="${RAW_BRANCH//\//-}"
+
+             SAFE_BRANCH=$(echo "$SAFE_BRANCH" | tr '[:upper:]' '[:lower:]')
+
+             CYPRESS_BASE_URL="https://${SAFE_BRANCH}.rescript-lang.pages.dev"
+          fi
+
+          echo "url=$CYPRESS_BASE_URL" >> "$GITHUB_OUTPUT"
       - name: Cypress E2E tests
         uses: cypress-io/github-action@v7
         with:
           install: false
           working-directory: apps/docs
           browser: chrome
-          config: baseUrl=${{ needs.deploy.outputs.deployment-url }}
+          config: baseUrl=${{ steps.cypress-base-url.outputs.url }}

.gitignore

@@ -37,6 +37,7 @@ apps/docs/scripts/gendocs.mjs
 apps/docs/scripts/generate_*.mjs
 apps/docs/scripts/gendocs.jsx
 apps/docs/scripts/generate_*.jsx
+apps/docs/scripts/LogAlgoliaEnvStatus.jsx
 
 # Generated via generate-llms script
 apps/docs/public/llms/manual/**/llm*.txt

README.md

@@ -33,6 +33,42 @@ yarn dev
 
 `yarn dev` prepares generated assets, starts the ReScript watcher, runs the React Router/Vite dev server, and serves the built client through Wrangler Pages.
 
+## Search and DocSearch
+
+Search is powered by Algolia DocSearch. The DocSearch crawler owns indexing and index settings; site builds and deployments do not upload records, replace indexes, or use an Algolia admin/write key.
+
+The frontend only needs public DocSearch runtime variables:
+
+```sh
+VITE_ALGOLIA_APP_ID="..."
+VITE_ALGOLIA_INDEX_NAME="..."
+VITE_ALGOLIA_SEARCH_API_KEY="..."
+```
+
+The GitHub deploy workflow passes the public GitHub secrets named `VITE_ALGOLIA_APP_ID`, `VITE_ALGOLIA_INDEX_NAME`, and `VITE_ALGOLIA_SEARCH_API_KEY` to the `yarn build` step. `VITE_ALGOLIA_INDEX_NAME` is the full runtime index name; the workflow does not add `prod_` or `dev_` prefixes. Builds and deployments should not configure or export Algolia admin/write keys.
+
+DocSearch crawl quality comes from the generated HTML. Searchable page bodies use `DocSearch-content`, each crawlable section provides a hidden `DocSearch-lvl0` marker such as `Manual`, `API`, `React`, `Syntax Lookup`, `Community`, or `Blog`, and headings own unique `id` attributes for section links.
+
+The crawler configuration should use selectors shaped like this:
+
+```js
+recordProps: {
+  lvl0: {
+    selectors: ".DocSearch-lvl0",
+    defaultValue: "Documentation",
+  },
+  lvl1: [".DocSearch-content h1", "main h1", "h1", "head > title"],
+  lvl2: [".DocSearch-content h2", "main h2", "h2"],
+  lvl3: [".DocSearch-content h3", "main h3", "h3"],
+  lvl4: [".DocSearch-content h4", "main h4", "h4"],
+  lvl5: [".DocSearch-content h5", "main h5", "h5"],
+  lvl6: [".DocSearch-content h6", "main h6", "h6"],
+  content: [".DocSearch-content p, .DocSearch-content li"],
+}
+```
+
+Production crawler start URLs, ranking, and crawler schedules live in the Algolia dashboard. The build generates `sitemap.xml` from the prerendered HTML pages so the crawler can use the deployed sitemap.
+
 ## Project Structure Overview
 
 - `app/`: React Router app shell, layouts, route definitions, and route modules

apps/docs/__tests__/AlgoliaConfig_.test.res

@@ -0,0 +1,27 @@
+open Vitest
+
+test("publicConfigFrom returns config when all public vars are present", async () => {
+  let result = AlgoliaConfig.publicConfigFrom(
+    ~appId=Some("app_123"),
+    ~indexName=Some("rescript_lang"),
+    ~searchApiKey=Some("search_123"),
+  )
+
+  let expected: AlgoliaConfig.publicConfig = {
+    appId: "app_123",
+    indexName: "rescript_lang",
+    searchApiKey: "search_123",
+  }
+
+  expect(result)->toEqual(Some(expected))
+})
+
+test("publicConfigFrom reports missing public vars in declaration order", async () => {
+  let result = AlgoliaConfig.missingPublicVars(
+    ~appId=None,
+    ~indexName=Some("rescript_lang"),
+    ~searchApiKey=None,
+  )
+
+  expect(result)->toEqual(["VITE_ALGOLIA_APP_ID", "VITE_ALGOLIA_SEARCH_API_KEY"])
+})

apps/docs/__tests__/AlgoliaEnvStatus_.test.res

@@ -0,0 +1,19 @@
+open Vitest
+
+test("reports missing public vars in declaration order", async () => {
+  let env = Dict.fromArray([
+    ("VITE_ALGOLIA_APP_ID", ""),
+    ("VITE_ALGOLIA_INDEX_NAME", "rescript_lang"),
+  ])
+
+  expect(AlgoliaEnvStatus.getMissingPublicAlgoliaVars(~env))->toEqual([
+    "VITE_ALGOLIA_APP_ID",
+    "VITE_ALGOLIA_SEARCH_API_KEY",
+  ])
+})
+
+test("formats the disabled search warning", async () => {
+  expect(AlgoliaEnvStatus.formatDisabledMessage(["VITE_ALGOLIA_APP_ID"]))->toBe(
+    "Algolia search disabled: missing VITE_ALGOLIA_APP_ID",
+  )
+})

apps/docs/__tests__/BlogArticle_.test.res

@@ -1,6 +1,8 @@
 open ReactRouter
 open Vitest
 
+@get external textContent: WebAPI.DOMAPI.element => string = "textContent"
+
 let mockAuthor: BlogFrontmatter.author = {
   username: "test-author",
   fullname: "Test Author",
@@ -46,6 +48,30 @@ test("desktop blog article renders header, author, date, and body", async () =>
   await element(wrapper)->toMatchScreenshot("desktop-blog-article")
 })
 
+test("blog article marks body content for DocSearch crawling", async () => {
+  await viewport(1440, 900)
+
+  let _screen = await render(
+    <BrowserRouter>
+      <BlogArticle frontmatter=mockFrontmatter isArchived=false path="/blog/test-article">
+        <p> {React.string("This is the blog post body content for testing.")} </p>
+      </BlogArticle>
+    </BrowserRouter>,
+  )
+
+  switch document->WebAPI.Document.querySelector("article.DocSearch-content") {
+  | Value(_) => ()
+  | Null => failwith("expected blog article body to be marked as DocSearch content")
+  }
+
+  let lvl0 = switch document->WebAPI.Document.querySelector("article .DocSearch-lvl0") {
+  | Value(element) => element
+  | Null => failwith("expected blog article to render a DocSearch lvl0 marker")
+  }
+
+  expect(lvl0->textContent)->toBe("Blog")
+})
+
 test("desktop archived blog article shows warning banner", async () => {
   await viewport(1440, 900)
 

apps/docs/__tests__/DocsLayout_.test.res

@@ -1,6 +1,8 @@
 open ReactRouter
 open Vitest
 
+@get external textContent: WebAPI.DOMAPI.element => string = "textContent"
+
 let mockCategories: array<SidebarLayout.Sidebar.Category.t> = [
   {
     name: "Overview",
@@ -57,6 +59,41 @@ test("desktop docs layout shows sidebar with categories", async () => {
   await element(wrapper)->toMatchScreenshot("desktop-docs-layout")
 })
 
+test("docs layout marks the textual content for DocSearch crawling", async () => {
+  await viewport(1440, 900)
+
+  let screen = await render(
+    <MemoryRouter initialEntries=["/docs/manual/introduction"]>
+      <DocsLayout categories=mockCategories activeToc=mockToc docSearchLvl0="Manual">
+        <div> {React.string("This is the documentation content.")} </div>
+      </DocsLayout>
+    </MemoryRouter>,
+  )
+
+  let _mainContent = await screen->getByTestId("side-layout-children")
+
+  let mainContent = switch document->WebAPI.Document.querySelector(
+    "[data-testid='side-layout-children']",
+  ) {
+  | Value(element) => element
+  | Null => failwith("expected docs layout main content")
+  }
+
+  let className = switch mainContent->WebAPI.Element.getAttribute("class") {
+  | Value(value) => value
+  | Null => ""
+  }
+
+  expect(className->String.includes("DocSearch-content"))->toBe(true)
+
+  let lvl0 = switch document->WebAPI.Document.querySelector(".DocSearch-lvl0") {
+  | Value(element) => element
+  | Null => failwith("expected docs layout to render a DocSearch lvl0 marker")
+  }
+
+  expect(lvl0->textContent)->toBe("Manual")
+})
+
 test("desktop docs layout shows table of contents entries", async () => {
   await viewport(1440, 900)
 

apps/docs/__tests__/DocsOverview_.test.res

@@ -49,6 +49,39 @@ test("desktop docs overview shows ecosystem links", async () => {
   await element(wrapper)->toMatchScreenshot("desktop-docs-overview-ecosystem")
 })
 
+test("docs overview uses unversioned docs links", async () => {
+  await viewport(1440, 900)
+
+  let _screen = await render(
+    <MemoryRouter initialEntries=["/docs"]>
+      <div dataTestId="docs-overview-wrapper">
+        <DocsOverview.default />
+      </div>
+    </MemoryRouter>,
+  )
+
+  let overviewLink = switch document->WebAPI.Document.querySelector(
+    "a[href='/docs/manual/introduction']",
+  ) {
+  | Value(link) => link
+  | Null => failwith("expected docs overview to link to the unversioned manual introduction")
+  }
+  await element(overviewLink)->toBeVisible
+
+  let genTypeLink = switch document->WebAPI.Document.querySelector(
+    "a[href='/docs/manual/typescript-integration']",
+  ) {
+  | Value(link) => link
+  | Null => failwith("expected docs overview to link to the unversioned GenType docs page")
+  }
+  await element(genTypeLink)->toBeVisible
+
+  switch document->WebAPI.Document.querySelector("a[href*='/docs/manual/v']") {
+  | Value(_) => failwith("expected docs overview to avoid versioned manual links")
+  | Null => ()
+  }
+})
+
 test("mobile docs overview", async () => {
   await viewport(600, 1200)
 

apps/docs/__tests__/MarkdownComponents_.test.res

@@ -21,6 +21,69 @@ test("renders headings h1 through h5", async () => {
   await element(wrapper)->toMatchScreenshot("markdown-headings")
 })
 
+test("h1 keeps the generated markdown id for DocSearch", async () => {
+  await viewport(1440, 900)
+
+  let _screen = await render(
+    <div>
+      <Markdown.H1 id="heading-level-1"> {React.string("Heading Level 1")} </Markdown.H1>
+    </div>,
+  )
+
+  switch document->WebAPI.Document.querySelector("h1#heading-level-1") {
+  | Value(_) => ()
+  | Null => failwith("expected markdown h1 to keep the generated id")
+  }
+})
+
+test("markdown headings expose explicit DocSearch hierarchy markers", async () => {
+  await viewport(1440, 900)
+
+  let _screen = await render(
+    <div>
+      <Markdown.H1 id="heading-level-1"> {React.string("Heading Level 1")} </Markdown.H1>
+      <Markdown.H2 id="heading-level-2"> {React.string("Heading Level 2")} </Markdown.H2>
+      <Markdown.H3 id="heading-level-3"> {React.string("Heading Level 3")} </Markdown.H3>
+      <Markdown.H4 id="heading-level-4"> {React.string("Heading Level 4")} </Markdown.H4>
+      <Markdown.H5 id="heading-level-5"> {React.string("Heading Level 5")} </Markdown.H5>
+    </div>,
+  )
+
+  switch document->WebAPI.Document.querySelector("h1.DocSearch-lvl1#heading-level-1") {
+  | Value(_) => ()
+  | Null => failwith("expected h1 to expose DocSearch lvl1")
+  }
+  switch document->WebAPI.Document.querySelector("h2.DocSearch-lvl2#heading-level-2") {
+  | Value(_) => ()
+  | Null => failwith("expected h2 to expose DocSearch lvl2")
+  }
+  switch document->WebAPI.Document.querySelector("h3.DocSearch-lvl3#heading-level-3") {
+  | Value(_) => ()
+  | Null => failwith("expected h3 to expose DocSearch lvl3")
+  }
+  switch document->WebAPI.Document.querySelector("h4.DocSearch-lvl4#heading-level-4") {
+  | Value(_) => ()
+  | Null => failwith("expected h4 to expose DocSearch lvl4")
+  }
+  switch document->WebAPI.Document.querySelector("h5.DocSearch-lvl5#heading-level-5") {
+  | Value(_) => ()
+  | Null => failwith("expected h5 to expose DocSearch lvl5")
+  }
+})
+
+test("heading anchor links do not duplicate heading ids", async () => {
+  await viewport(1440, 900)
+
+  let _screen = await render(
+    <div>
+      <Markdown.H2 id="duplicate-check"> {React.string("Duplicate Check")} </Markdown.H2>
+    </div>,
+  )
+
+  let matches = document->WebAPI.Document.querySelectorAll("[id='duplicate-check']")
+  expect(matches.length)->toBe(1)
+})
+
 test("renders paragraph, strong, and intro", async () => {
   await viewport(1440, 900)
 

apps/docs/__tests__/Meta_.test.res

@@ -0,0 +1,19 @@
+open Vitest
+
+let getMetaContent = name => {
+  switch document->WebAPI.Document.querySelector(`meta[name='${name}']`) {
+  | Value(element) =>
+    switch element->WebAPI.Element.getAttribute("content") {
+    | Value(content) => content
+    | Null => failwith(`expected ${name} meta tag to have content`)
+    }
+  | Null => failwith(`expected ${name} meta tag`)
+  }
+}
+
+test("renders DocSearch crawler meta tags", async () => {
+  let _screen = await render(<Meta />)
+
+  expect(getMetaContent("docsearch:language"))->toBe("en")
+  expect(getMetaContent("docsearch:version"))->toBe("v12,latest")
+})