{React.string("This is the blog post body content for testing.")}
+ tags", async () => {
+ expect(Search.markdownToHtml("`Array.map`"))->toBe("Array.map")
+})
+
+test("markdownToHtml converts multiple backtick spans", async () => {
+ expect(Search.markdownToHtml("Use `map` and `filter`"))->toBe(
+ "Use map and filter",
+ )
+})
+
+test("markdownToHtml converts **text** to tags", async () => {
+ expect(Search.markdownToHtml("**important**"))->toBe("important")
+})
+
+test("markdownToHtml converts bold within a sentence", async () => {
+ expect(Search.markdownToHtml("This is **very** important"))->toBe(
+ "This is very important",
+ )
+})
+
+test("markdownToHtml converts *text* to tags", async () => {
+ expect(Search.markdownToHtml("*emphasis*"))->toBe("emphasis")
+})
+
+test("markdownToHtml converts italic within a sentence", async () => {
+ expect(Search.markdownToHtml("This is *quite* nice"))->toBe("This is quite nice")
+})
+
+test("markdownToHtml converts double newline to
", async () => {
+ expect(Search.markdownToHtml("first\n\nsecond"))->toBe("first
second")
+})
+
+test("markdownToHtml converts triple+ newlines to a single
", async () => {
+ expect(Search.markdownToHtml("first\n\n\nsecond"))->toBe("first
second")
+})
+
+test("markdownToHtml converts single newline to a space", async () => {
+ expect(Search.markdownToHtml("first\nsecond"))->toBe("first second")
+})
+
+test("markdownToHtml trims leading whitespace", async () => {
+ expect(Search.markdownToHtml(" hello"))->toBe("hello")
+})
+
+test("markdownToHtml trims trailing whitespace", async () => {
+ expect(Search.markdownToHtml("hello "))->toBe("hello")
+})
+
+test("markdownToHtml trims both sides", async () => {
+ expect(Search.markdownToHtml(" hello "))->toBe("hello")
+})
+
+test("markdownToHtml handles empty string", async () => {
+ expect(Search.markdownToHtml(""))->toBe("")
+})
+
+test("markdownToHtml passes plain text through unchanged", async () => {
+ expect(Search.markdownToHtml("just plain text"))->toBe("just plain text")
+})
+
+test("markdownToHtml applies multiple transformations together", async () => {
+ expect(
+ Search.markdownToHtml("Use `map` on **arrays**.\n\nSee [docs](http://x.com) for *details*."),
+ )->toBe("Use map on arrays.
See docs for details.")
+})
+
+test(
+ "markdownToHtml still converts bold inside code because regexes run sequentially",
+ async () => {
+ expect(Search.markdownToHtml("`**notbold**`"))->toBe("notbold")
+ },
+)
+
+test("getHighlightedTitle renders crawler API titles as value names", async () => {
+ let hit = withHierarchy(
+ makeHit(
+ ~type_=Content,
+ ~url="https://rescript-lang.org/docs/manual/api/stdlib/array/#value-mapWithIndex",
+ ),
+ ~lvl0="Array",
+ ~lvl1="mapWithIndex",
+ )
+ let hit = {
+ ...hit,
+ _snippetResult: {
+ content: Nullable.make(highlightedValue("See Array.map on MDN.")),
+ },
+ }
+
+ expect(Search.getHighlightedTitle(hit))->toBe("mapWithIndex")
+})
+
+test(
+ "getHighlightedTitle prefers real hierarchy highlights when Algolia returns them",
+ async () => {
+ let highlightedHierarchy: DocSearch.highlightedHierarchy = {
+ lvl0: Nullable.null,
+ lvl1: Nullable.null,
+ lvl2: Nullable.make(highlightedValue("Section title")),
+ lvl3: Nullable.null,
+ lvl4: Nullable.null,
+ lvl5: Nullable.null,
+ lvl6: Nullable.null,
+ }
+ let hit = {
+ ...makeHit(~type_=Lvl2, ~url="https://rescript-lang.org/docs/manual/page#section"),
+ _highlightResult: {hierarchy: Nullable.make(highlightedHierarchy)},
+ }
+
+ expect(Search.getHighlightedTitle(hit))->toBe("Section title")
+ },
+)
+
+test("getContentHtml prefers crawler snippet markup over plain content", async () => {
+ let hit = {
+ ...makeHit(~type_=Content, ~url="https://rescript-lang.org/docs/manual/api/stdlib/array/"),
+ content: Nullable.make("map(array, fn) returns a new array."),
+ _snippetResult: {
+ content: Nullable.make(highlightedValue("map(array, fn) returns a new array.")),
+ },
+ }
+
+ expect(Search.getContentHtml(hit))->toEqual(
+ Some("map(array, fn) returns a new array."),
+ )
+})
+
+test("hitComponent routes relative hit URLs through React Router", async () => {
+ await viewport(1440, 500)
+
+ let hit = makeHit(~type_=Lvl1, ~url="/docs/manual/api/stdlib/list/")
+
+ let screen = await render(
+
+ ,
+ )
+
+ await element(await screen->getByText("/"))->toBeVisible
+ await (await screen->getByText("Test Page"))->click
+ await element(await screen->getByText("/docs/manual/api/stdlib/list/"))->toBeVisible
+})
+
+test(
+ "getContentHtml falls back to plain content when crawler hit has no snippet result",
+ async () => {
+ let hit: DocSearch.docSearchHit = Obj.magic(
+ Dict.fromArray([
+ ("objectID", "crawler-hit"),
+ ("content", "map(array, fn) returns a new array."),
+ ("url", "https://rescript-lang.org/docs/manual/api/stdlib/array/#value-map"),
+ ("type", "content"),
+ (
+ "hierarchy",
+ Obj.magic(
+ Dict.fromArray([
+ ("lvl0", Obj.magic("Array")),
+ ("lvl1", Obj.magic("map")),
+ ("lvl2", Obj.magic(Nullable.null)),
+ ("lvl3", Obj.magic(Nullable.null)),
+ ("lvl4", Obj.magic(Nullable.null)),
+ ("lvl5", Obj.magic(Nullable.null)),
+ ("lvl6", Obj.magic(Nullable.null)),
+ ]),
+ ),
+ ),
+ ]),
+ )
+
+ expect(Search.getContentHtml(hit))->toEqual(Some("map(array, fn) returns a new array."))
+ },
+)
+
+test("search error boundary catches render errors without replacing surrounding page", async () => {
+ await viewport(1440, 500)
+
+ let screen = await render(
+
+ {React.string("Docs page stays rendered")}
+ ()}>
+
+ ,
+ )
+
+ await element(await screen->getByText("Docs page stays rendered"))->toBeVisible
+ await element(await screen->getByText("Search unavailable"))->toBeVisible
+})
+
+// ---------------------------------------------------------------------------
+// isChildHit
+// ---------------------------------------------------------------------------
+
+test("isChildHit treats Lvl2 as a child hit", async () => {
+ expect(Search.isChildHit(makeHit(~type_=Lvl2, ~url="https://example.com/page")))->toBe(true)
+})
+
+test("isChildHit treats Lvl3 as a child hit", async () => {
+ expect(Search.isChildHit(makeHit(~type_=Lvl3, ~url="https://example.com/page")))->toBe(true)
+})
+
+test("isChildHit treats Lvl4 as a child hit", async () => {
+ expect(Search.isChildHit(makeHit(~type_=Lvl4, ~url="https://example.com/page")))->toBe(true)
+})
+
+test("isChildHit treats Lvl5 as a child hit", async () => {
+ expect(Search.isChildHit(makeHit(~type_=Lvl5, ~url="https://example.com/page")))->toBe(true)
+})
+
+test("isChildHit treats Lvl6 as a child hit", async () => {
+ expect(Search.isChildHit(makeHit(~type_=Lvl6, ~url="https://example.com/page")))->toBe(true)
+})
+
+test("isChildHit treats Content as a child hit", async () => {
+ expect(Search.isChildHit(makeHit(~type_=Content, ~url="https://example.com/page")))->toBe(true)
+})
+
+test("isChildHit treats Lvl2 as a child hit even without a hash in the URL", async () => {
+ expect(Search.isChildHit(makeHit(~type_=Lvl2, ~url="https://example.com/no-hash")))->toBe(true)
+})
+
+test("isChildHit treats Content as a child hit even with a hash in the URL", async () => {
+ expect(Search.isChildHit(makeHit(~type_=Content, ~url="https://example.com/page#section")))->toBe(
+ true,
+ )
+})
+
+test("isChildHit treats Lvl0 without a hash as not a child hit", async () => {
+ expect(Search.isChildHit(makeHit(~type_=Lvl0, ~url="https://example.com/page")))->toBe(false)
+})
+
+test("isChildHit treats Lvl0 with a hash as a child hit", async () => {
+ expect(Search.isChildHit(makeHit(~type_=Lvl0, ~url="https://example.com/page#section")))->toBe(
+ true,
+ )
+})
+
+test("isChildHit treats Lvl0 with a trailing # as a child hit", async () => {
+ expect(Search.isChildHit(makeHit(~type_=Lvl0, ~url="https://example.com/page#")))->toBe(true)
+})
+
+test("isChildHit treats Lvl1 without a hash as not a child hit", async () => {
+ expect(Search.isChildHit(makeHit(~type_=Lvl1, ~url="https://example.com/page")))->toBe(false)
+})
+
+test("isChildHit treats Lvl1 with a hash as a child hit", async () => {
+ expect(Search.isChildHit(makeHit(~type_=Lvl1, ~url="https://example.com/page#heading")))->toBe(
+ true,
+ )
+})
+
+test("isChildHit treats Lvl1 with a deeply nested hash anchor as a child hit", async () => {
+ expect(
+ Search.isChildHit(
+ makeHit(~type_=Lvl1, ~url="https://example.com/docs/manual/api#some-section"),
+ ),
+ )->toBe(true)
+})
+
+test("isChildHit treats Lvl1 with an empty URL as not a child hit", async () => {
+ expect(Search.isChildHit(makeHit(~type_=Lvl1, ~url="")))->toBe(false)
+})
+
+test("toRelativeSiteUrl strips the site origin from an absolute URL", async () => {
+ let result = Search.toRelativeSiteUrl(
+ "https://rescript-lang.org/docs/manual/introduction#what-is-rescript",
+ ~siteUrl="https://rescript-lang.org/",
+ )
+
+ expect(result)->toBe("/docs/manual/introduction#what-is-rescript")
+})
+
+test("toRelativeSiteUrl leaves absolute URLs unchanged when siteUrl is empty", async () => {
+ let result = Search.toRelativeSiteUrl(
+ "https://rescript-lang.org/docs/manual/introduction#what-is-rescript",
+ ~siteUrl="",
+ )
+
+ expect(result)->toBe("https://rescript-lang.org/docs/manual/introduction#what-is-rescript")
+})
+
+test("normalizeHitUrls rewrites absolute site URLs to relative paths", async () => {
+ let hit = makeHit(
+ ~type_=Lvl1,
+ ~url="https://rescript-lang.org/docs/manual/typescript-integration#gentype",
+ )
+ let result = Search.normalizeHitUrls([hit], ~siteUrl="https://rescript-lang.org/")
+
+ expect(result[0]->Option.map(hit => hit.url))->toEqual(
+ Some("/docs/manual/typescript-integration#gentype"),
+ )
+ expect(result[0]->Option.flatMap(hit => hit.url_without_anchor->Nullable.toOption))->toEqual(
+ Some("/docs/manual/typescript-integration#gentype"),
+ )
+})
+
+test("normalizeHitUrls tolerates crawler hits without url_without_anchor", async () => {
+ let hit: DocSearch.docSearchHit = Obj.magic(
+ Dict.fromArray([
+ ("objectID", "crawler-hit"),
+ ("content", "map(array, fn) returns a new array."),
+ ("url", "https://rescript-lang.org/docs/manual/api/stdlib/array/#value-map"),
+ ("type", "content"),
+ (
+ "hierarchy",
+ Obj.magic(
+ Dict.fromArray([
+ ("lvl0", Obj.magic("Array")),
+ ("lvl1", Obj.magic("map")),
+ ("lvl2", Obj.magic(Nullable.null)),
+ ("lvl3", Obj.magic(Nullable.null)),
+ ("lvl4", Obj.magic(Nullable.null)),
+ ("lvl5", Obj.magic(Nullable.null)),
+ ("lvl6", Obj.magic(Nullable.null)),
+ ]),
+ ),
+ ),
+ ]),
+ )
+
+ let result = Search.normalizeHitUrls([hit], ~siteUrl="https://rescript-lang.org/")
+
+ expect(result[0]->Option.map(hit => hit.url))->toEqual(
+ Some("/docs/manual/api/stdlib/array/#value-map"),
+ )
+ expect(result[0]->Option.flatMap(hit => hit.url_without_anchor->Nullable.toOption))->toEqual(
+ Some("/docs/manual/api/stdlib/array/"),
+ )
+})
+
+test("normalizeHitUrls keeps API hit order while separating Belt group labels", async () => {
+ let beltHit = withHierarchy(
+ {
+ ...makeHit(
+ ~type_=Content,
+ ~url="https://rescript-lang.org/docs/manual/api/belt/array/#value-map",
+ ),
+ objectID: "belt-array-map",
+ },
+ ~lvl0="Array",
+ ~lvl1="map",
+ )
+ let stdlibHit = withHierarchy(
+ {
+ ...makeHit(
+ ~type_=Content,
+ ~url="https://rescript-lang.org/docs/manual/api/stdlib/array/#value-map",
+ ),
+ objectID: "stdlib-array-map",
+ },
+ ~lvl0="Array",
+ ~lvl1="map",
+ )
+
+ let result = Search.normalizeHitUrls([beltHit, stdlibHit], ~siteUrl="https://rescript-lang.org/")
+
+ expect(result[0]->Option.map(hit => hit.objectID))->toEqual(Some("belt-array-map"))
+ expect(result[0]->Option.flatMap(hit => hit.hierarchy.lvl0->Nullable.toOption))->toEqual(
+ Some("Belt.Array"),
+ )
+ expect(result[1]->Option.map(hit => hit.objectID))->toEqual(Some("stdlib-array-map"))
+ expect(result[1]->Option.flatMap(hit => hit.hierarchy.lvl0->Nullable.toOption))->toEqual(
+ Some("Array"),
+ )
+})
+
+test("renders disabled search copy when Algolia config is missing", async () => {
+ await viewport(1440, 500)
+
+ let screen = await render(
+
+ https://preview.example.com/
+
+
+ https://preview.example.com/blog/
+
+
+ https://preview.example.com/docs/manual/introduction/
+
+
+`)
+})
diff --git a/apps/docs/__tests__/SyntaxLookup_.test.res b/apps/docs/__tests__/SyntaxLookup_.test.res
index 38b3bb864..6568b62c4 100644
--- a/apps/docs/__tests__/SyntaxLookup_.test.res
+++ b/apps/docs/__tests__/SyntaxLookup_.test.res
@@ -1,6 +1,8 @@
open ReactRouter
open Vitest
+@get external textContent: WebAPI.DOMAPI.element => string = "textContent"
+
let mockItems: array = [
{
id: "as-decorator",
@@ -87,6 +89,30 @@ test("desktop syntax lookup with active item shows detail box", async () => {
await element(wrapper)->toMatchScreenshot("desktop-syntax-lookup-active")
})
+test("syntax lookup detail marks active content for DocSearch crawling", async () => {
+ await viewport(1440, 900)
+
+ let _screen = await render(
+
+ Array.getUnsafe(0)}>
+ {React.string("Detail content for @as decorator.")}
+
+ ,
+ )
+
+ switch document->WebAPI.Document.querySelector(".DocSearch-content h1") {
+ | Value(heading) => expect(heading->textContent)->toBe("@as")
+ | Null => failwith("expected active syntax detail to provide a DocSearch heading")
+ }
+
+ let lvl0 = switch document->WebAPI.Document.querySelector(".DocSearch-content .DocSearch-lvl0") {
+ | Value(element) => element
+ | Null => failwith("expected syntax detail to render a DocSearch lvl0 marker")
+ }
+
+ expect(lvl0->textContent)->toBe("Syntax Lookup")
+})
+
test("mobile syntax lookup", async () => {
await viewport(600, 1200)
diff --git a/apps/docs/__tests__/Url_.test.res b/apps/docs/__tests__/Url_.test.res
new file mode 100644
index 000000000..fd29c2185
--- /dev/null
+++ b/apps/docs/__tests__/Url_.test.res
@@ -0,0 +1,29 @@
+open Vitest
+
+test("Url.parse splits an unversioned route into path segments", async () => {
+ let result = Url.parse("/docs/manual/introduction")
+ expect(result.base)->toEqual(["docs", "manual", "introduction"])
+ expect(result.pagepath)->toEqual([])
+ expect(result.fullpath)->toEqual(["docs", "manual", "introduction"])
+})
+
+test("Url.parse treats version-like segments as ordinary path content", async () => {
+ let result = Url.parse("/docs/manual/v12.0.0/introduction")
+ expect(result.base)->toEqual(["docs", "manual", "v12.0.0", "introduction"])
+ expect(result.pagepath)->toEqual([])
+ expect(result.fullpath)->toEqual(["docs", "manual", "v12.0.0", "introduction"])
+})
+
+test("Url.parse treats latest as ordinary path content", async () => {
+ let result = Url.parse("/docs/manual/latest/arrays")
+ expect(result.base)->toEqual(["docs", "manual", "latest", "arrays"])
+ expect(result.pagepath)->toEqual([])
+ expect(result.fullpath)->toEqual(["docs", "manual", "latest", "arrays"])
+})
+
+test("Url.parse parses routes outside docs without special handling", async () => {
+ let result = Url.parse("/community/overview")
+ expect(result.base)->toEqual(["community", "overview"])
+ expect(result.pagepath)->toEqual([])
+ expect(result.fullpath)->toEqual(["community", "overview"])
+})
diff --git a/apps/docs/__tests__/__screenshots__/Search_.test.jsx/markdownToHtml-combined-transformations-bold-inside-code-stays-as-is--code-matched-first--1.png b/apps/docs/__tests__/__screenshots__/Search_.test.jsx/markdownToHtml-combined-transformations-bold-inside-code-stays-as-is--code-matched-first--1.png
new file mode 100644
index 000000000..a35891721
Binary files /dev/null and b/apps/docs/__tests__/__screenshots__/Search_.test.jsx/markdownToHtml-combined-transformations-bold-inside-code-stays-as-is--code-matched-first--1.png differ
diff --git a/apps/docs/__tests__/__screenshots__/Search_.test.jsx/markdownToHtml-markdown-link-stripping-handles-link-with-empty-text-1.png b/apps/docs/__tests__/__screenshots__/Search_.test.jsx/markdownToHtml-markdown-link-stripping-handles-link-with-empty-text-1.png
new file mode 100644
index 000000000..a35891721
Binary files /dev/null and b/apps/docs/__tests__/__screenshots__/Search_.test.jsx/markdownToHtml-markdown-link-stripping-handles-link-with-empty-text-1.png differ
diff --git a/apps/docs/__tests__/__screenshots__/Url_.test.jsx/Url-parse-version-detection-parses-next-keyword-1.png b/apps/docs/__tests__/__screenshots__/Url_.test.jsx/Url-parse-version-detection-parses-next-keyword-1.png
new file mode 100644
index 000000000..a35891721
Binary files /dev/null and b/apps/docs/__tests__/__screenshots__/Url_.test.jsx/Url-parse-version-detection-parses-next-keyword-1.png differ
diff --git a/apps/docs/__tests__/__screenshots__/Url_.test.jsx/Url-parse-version-detection-parses-version-without-v-prefix--PR--1231--1.png b/apps/docs/__tests__/__screenshots__/Url_.test.jsx/Url-parse-version-detection-parses-version-without-v-prefix--PR--1231--1.png
new file mode 100644
index 000000000..a35891721
Binary files /dev/null and b/apps/docs/__tests__/__screenshots__/Url_.test.jsx/Url-parse-version-detection-parses-version-without-v-prefix--PR--1231--1.png differ
diff --git a/apps/docs/app/routes/ApiDocs.res b/apps/docs/app/routes/ApiDocs.res
index d8b010fa6..cb8ff93b8 100644
--- a/apps/docs/app/routes/ApiDocs.res
+++ b/apps/docs/app/routes/ApiDocs.res
@@ -288,7 +288,7 @@ let make = (props: props) => {
})
<>
- {name->React.string}
+ Url.normalizeAnchor}> {name->React.string}
children
+ children
}
module Data = {
diff --git a/apps/docs/app/routes/ApiOverviewRoute.res b/apps/docs/app/routes/ApiOverviewRoute.res
index 36ce0d55d..58fd5cc47 100644
--- a/apps/docs/app/routes/ApiOverviewRoute.res
+++ b/apps/docs/app/routes/ApiOverviewRoute.res
@@ -56,7 +56,7 @@ let default = () => {
+
=> {
- let url = Url.parse((route :> string))
-
- let (_, rest) = // Strip the "api" part of the url before creating the rest of the breadcrumbs
- Array.slice(url.pagepath, ~start=1)->Array.reduce((prefix.href, []), (acc, path) => {
- let (baseHref, ret) = acc
-
- let href = baseHref ++ ("/" ++ path)
-
- Array.push(
- ret,
- {
- Url.name: Url.prettyString(path),
- href,
- },
- )->ignore
- (href, ret)
- })
+ let (_, rest) =
+ // Strip the "/docs/manual/api" base path before creating the rest of the breadcrumbs
+ (route :> string)
+ ->String.split("/")
+ ->Array.filter(s => s !== "")
+ ->Array.slice(~start=3)
+ ->Array.reduce((prefix.href, []), (acc, path) => {
+ let (baseHref, ret) = acc
+
+ let href = baseHref ++ ("/" ++ path)
+
+ Array.push(
+ ret,
+ {
+ Url.name: Url.prettyString(path),
+ href,
+ },
+ )->ignore
+ (href, ret)
+ })
Array.concat([prefix], rest)->List.fromArray
}
diff --git a/apps/docs/app/routes/BlogArticle.res b/apps/docs/app/routes/BlogArticle.res
index 736dcd3d4..d2a343d08 100644
--- a/apps/docs/app/routes/BlogArticle.res
+++ b/apps/docs/app/routes/BlogArticle.res
@@ -142,7 +142,10 @@ let make = (props: props) => {
archivedNote
- children
+
+ {React.string("Blog")}
+ children
+
+
+
+
{React.string(item.name)}
children
}
diff --git a/apps/docs/package.json b/apps/docs/package.json
index dbe1267c3..03aa4d044 100644
--- a/apps/docs/package.json
+++ b/apps/docs/package.json
@@ -8,11 +8,13 @@
"scripts": {
"build:scripts": "yarn dlx tsdown@0.21.7 scripts/*.jsx -d _scripts --no-clean --ext .mjs",
"build:generate-llms": "node _scripts/generate_llms.mjs",
+ "build:generate-sitemap": "node _scripts/generate_sitemap.mjs build/client out",
"build:res": "rescript build --warn-error +3+8+11+12+26+27+31+32+33+34+35+39+44+45+110",
"build:sync-bundles": "node scripts/sync-playground-bundles.mjs",
"build:update-index": "yarn build:generate-llms && node _scripts/generate_feed.mjs > public/blog/feed.xml",
"build:vite": "react-router build",
- "build": "yarn build:res && yarn build:scripts && yarn build:update-index && yarn build:vite",
+ "check:algolia-public-env": "node _scripts/LogAlgoliaEnvStatus.mjs",
+ "build": "yarn build:res && yarn build:scripts && yarn check:algolia-public-env && yarn build:update-index && yarn build:vite && yarn build:generate-sitemap",
"ci:format": "cd ../.. && oxfmt --check",
"ci:test": "yarn vitest --run --browser.headless",
"clean:res": "rescript clean",
@@ -22,7 +24,7 @@
"dev:wrangler": "yarn wrangler pages dev build/client",
"dev": "yarn prepare && yarn dev:res & yarn dev:vite & yarn dev:wrangler",
"format": "cd ../.. && oxfmt && cd apps/docs && rescript format",
- "prepare": "yarn build:res && yarn build:scripts && yarn build:update-index",
+ "prepare": "yarn build:res && yarn build:scripts && yarn check:algolia-public-env && yarn build:update-index",
"preview": "yarn build && static-server build/client",
"reanalyze": "rescript-tools reanalyze -all-cmt .",
"test": "node scripts/test.mjs",
diff --git a/apps/docs/scripts/LogAlgoliaEnvStatus.res b/apps/docs/scripts/LogAlgoliaEnvStatus.res
new file mode 100644
index 000000000..887c08825
--- /dev/null
+++ b/apps/docs/scripts/LogAlgoliaEnvStatus.res
@@ -0,0 +1,19 @@
+@val @scope(("import", "meta")) external url: string = "url"
+
+let run = () => {
+ let missing = AlgoliaEnvStatus.getMissingPublicAlgoliaVars(~env=Node.Process.env)
+ if Array.length(missing) > 0 {
+ Console.warn(AlgoliaEnvStatus.formatDisabledMessage(missing))
+ }
+}
+
+let isMainModule = () =>
+ switch Node.Process.argv[1] {
+ | Some(entrypoint) =>
+ Node.URL.fileURLToPath(url) === Node.Path.resolve(Node.Process.cwd(), entrypoint)
+ | None => false
+ }
+
+let _ = if isMainModule() {
+ run()
+}
diff --git a/apps/docs/scripts/generate_sitemap.res b/apps/docs/scripts/generate_sitemap.res
new file mode 100644
index 000000000..d85dc9f44
--- /dev/null
+++ b/apps/docs/scripts/generate_sitemap.res
@@ -0,0 +1,47 @@
+let rec collectPagePaths = (dirPath, urlPath) => {
+ Node.Fs.readdirSync(dirPath)->Array.flatMap(entry => {
+ let fullPath = Node.Path.join2(dirPath, entry)
+ let stats = Node.Fs.statSync(fullPath)
+
+ if stats["isDirectory"]() {
+ let nextUrlPath = if urlPath === "" {
+ entry
+ } else {
+ urlPath ++ "/" ++ entry
+ }
+
+ collectPagePaths(fullPath, nextUrlPath)
+ } else if entry === "index.html" {
+ [urlPath === "" ? "/" : "/" ++ urlPath]
+ } else {
+ []
+ }
+ })
+}
+
+let outputDirs = {
+ let args = Node.Process.argv->Array.slice(~start=2)
+
+ switch args->Array.length {
+ | 0 => ["build/client"]
+ | _ => args
+ }
+}
+
+let sourceDir = outputDirs->Array.get(0)->Option.getOr("build/client")
+
+if !Node.Fs.existsSync(sourceDir) {
+ Console.error(`Cannot generate sitemap: ${sourceDir} does not exist`)
+ Node.Process.exit(1)
+}
+
+let baseUrl = Node.Process.env->Dict.get("VITE_DEPLOYMENT_URL")->Option.getOr("")
+let sitemap = sourceDir->collectPagePaths("")->Sitemap.render(~baseUrl)
+
+outputDirs->Array.forEach(outputDir => {
+ if Node.Fs.existsSync(outputDir) {
+ let filePath = Node.Path.join2(outputDir, "sitemap.xml")
+ Node.Fs.writeFileSync(filePath, sitemap, ~encoding="utf8")
+ Console.log(`Generated ${filePath}`)
+ }
+})
diff --git a/apps/docs/src/bindings/DocSearch.res b/apps/docs/src/bindings/DocSearch.res
index 0c42d8586..d51f22c5a 100644
--- a/apps/docs/src/bindings/DocSearch.res
+++ b/apps/docs/src/bindings/DocSearch.res
@@ -19,19 +19,39 @@ type hierarchy = {
lvl6: Nullable.t,
}
+type highlightedValue = {value: string}
+
+type highlightedHierarchy = {
+ lvl0: Nullable.t,
+ lvl1: Nullable.t,
+ lvl2: Nullable.t,
+ lvl3: Nullable.t,
+ lvl4: Nullable.t,
+ lvl5: Nullable.t,
+ lvl6: Nullable.t,
+}
+
+type highlightResult = {
+ hierarchy: Nullable.t,
+}
+
+type snippetResult = {
+ content: Nullable.t,
+}
+
type docSearchHit = {
objectID: string,
content: Nullable.t,
url: string,
- url_without_anchor: string,
+ url_without_anchor: Nullable.t,
@as("type") type_: contentType,
anchor: Nullable.t,
hierarchy: hierarchy,
// Additional field for deprecation information
deprecated: option,
// NOTE: docsearch need these two fields to highlight results
- _highlightResult: {.},
- _snippetResult: {.},
+ _highlightResult?: highlightResult,
+ _snippetResult?: snippetResult,
}
type transformItems = array
@@ -44,7 +64,12 @@ type item = {itemUrl: string}
type navigator = {navigate: item => unit}
-type searchParameters = {facetFilters: array}
+type searchParameters = {
+ facetFilters?: array,
+ hitsPerPage?: int,
+ distinct?: int,
+ attributesToSnippet?: array,
+}
@module("@docsearch/react") @react.component
external make: (
diff --git a/apps/docs/src/bindings/Env.res b/apps/docs/src/bindings/Env.res
index 29a6c4e1b..29e21321d 100644
--- a/apps/docs/src/bindings/Env.res
+++ b/apps/docs/src/bindings/Env.res
@@ -6,6 +6,41 @@ external deployment_url: option = "import.meta.env.VITE_DEPLOYMENT_URL"
// the root url of the site, e.g. "https://rescript-lang.org/" or "http://localhost:5173/"
let root_url = switch deployment_url {
-| Some(url) => url
+| Some(url) if url !== "" => url
| None => dev ? "http://localhost:5173/" : "https://rescript-lang.org/"
+| Some(_) => "https://rescript-lang.org/"
}
+
+// Algolia search configuration (read from .env via Vite)
+external algoliaAppIdRaw: option = "import.meta.env.VITE_ALGOLIA_APP_ID"
+external algoliaIndexNameRaw: option = "import.meta.env.VITE_ALGOLIA_INDEX_NAME"
+external algoliaSearchApiKeyRaw: option = "import.meta.env.VITE_ALGOLIA_SEARCH_API_KEY"
+
+let algoliaMissingPublicVars = AlgoliaConfig.missingPublicVars(
+ ~appId=algoliaAppIdRaw,
+ ~indexName=algoliaIndexNameRaw,
+ ~searchApiKey=algoliaSearchApiKeyRaw,
+)
+
+let algoliaPublicConfig = AlgoliaConfig.publicConfigFrom(
+ ~appId=algoliaAppIdRaw,
+ ~indexName=algoliaIndexNameRaw,
+ ~searchApiKey=algoliaSearchApiKeyRaw,
+)
+
+let algolia_app_id = switch algoliaPublicConfig {
+| Some(config) => config.appId
+| None => ""
+}
+
+let algolia_index_name = switch algoliaPublicConfig {
+| Some(config) => config.indexName
+| None => ""
+}
+
+let algolia_search_api_key = switch algoliaPublicConfig {
+| Some(config) => config.searchApiKey
+| None => ""
+}
+
+let algolia_read_api_key = algolia_search_api_key
diff --git a/apps/docs/src/bindings/Mdast.res b/apps/docs/src/bindings/Mdast.res
index 565117d31..c9fd2c016 100644
--- a/apps/docs/src/bindings/Mdast.res
+++ b/apps/docs/src/bindings/Mdast.res
@@ -3,6 +3,12 @@ type tree
@module("mdast-util-from-markdown")
external fromMarkdown: string => tree = "fromMarkdown"
+@module("mdast-util-to-string")
+external toString: {..} => string = "toString"
+
+@module("unist-util-visit")
+external visit: (tree, string, {..} => unit) => unit = "visit"
+
@unboxed
type listType =
| @as("list") List
diff --git a/apps/docs/src/bindings/Vitest.res b/apps/docs/src/bindings/Vitest.res
index 1f15e6f79..c2428c72d 100644
--- a/apps/docs/src/bindings/Vitest.res
+++ b/apps/docs/src/bindings/Vitest.res
@@ -86,6 +86,9 @@ external click: element => promise = "click"
@send
external toBe: (expect, 'a) => unit = "toBe"
+@send
+external toEqual: (expect, 'a) => unit = "toEqual"
+
@send
external toHaveBeenCalled: expect => unit = "toHaveBeenCalled"
diff --git a/apps/docs/src/common/AlgoliaConfig.res b/apps/docs/src/common/AlgoliaConfig.res
new file mode 100644
index 000000000..e486ee425
--- /dev/null
+++ b/apps/docs/src/common/AlgoliaConfig.res
@@ -0,0 +1,37 @@
+type publicConfig = {
+ appId: string,
+ indexName: string,
+ searchApiKey: string,
+}
+
+let isPresent = value =>
+ switch value {
+ | Some(v) => v !== ""
+ | None => false
+ }
+
+let missingPublicVars = (~appId, ~indexName, ~searchApiKey): array => {
+ let missing = []
+ if !isPresent(appId) {
+ missing->Array.push("VITE_ALGOLIA_APP_ID")
+ }
+ if !isPresent(indexName) {
+ missing->Array.push("VITE_ALGOLIA_INDEX_NAME")
+ }
+ if !isPresent(searchApiKey) {
+ missing->Array.push("VITE_ALGOLIA_SEARCH_API_KEY")
+ }
+ missing
+}
+
+let publicConfigFrom = (~appId, ~indexName, ~searchApiKey): option =>
+ switch (appId, indexName, searchApiKey) {
+ | (Some(appId), Some(indexName), Some(searchApiKey))
+ if missingPublicVars(
+ ~appId=Some(appId),
+ ~indexName=Some(indexName),
+ ~searchApiKey=Some(searchApiKey),
+ )->Array.length === 0 =>
+ Some({appId, indexName, searchApiKey})
+ | _ => None
+ }
diff --git a/apps/docs/src/common/AlgoliaEnvStatus.res b/apps/docs/src/common/AlgoliaEnvStatus.res
new file mode 100644
index 000000000..20c52ceca
--- /dev/null
+++ b/apps/docs/src/common/AlgoliaEnvStatus.res
@@ -0,0 +1,12 @@
+let publicKeys = ["VITE_ALGOLIA_APP_ID", "VITE_ALGOLIA_INDEX_NAME", "VITE_ALGOLIA_SEARCH_API_KEY"]
+
+let getMissingPublicAlgoliaVars = (~env: Dict.t): array =>
+ publicKeys->Array.filter(key =>
+ switch env->Dict.get(key) {
+ | None | Some("") => true
+ | Some(_) => false
+ }
+ )
+
+let formatDisabledMessage = (missing: array) =>
+ `Algolia search disabled: missing ${missing->Array.join(", ")}`
diff --git a/apps/docs/src/common/Constants.res b/apps/docs/src/common/Constants.res
index 3e1e23462..9183573f6 100644
--- a/apps/docs/src/common/Constants.res
+++ b/apps/docs/src/common/Constants.res
@@ -19,6 +19,11 @@ let versions = {
let latestVersion = (versions.latest, versions.latest->Semver.tryGetMajorString)
+let docSearchVersionTokens = {
+ let (_, majorVersion) = latestVersion
+ [majorVersion, "latest"]
+}
+
// This is used for the version dropdown in the manual layouts
let allManualVersions = [
latestVersion,
@@ -46,14 +51,12 @@ let dropdownLabelNext = "--- Next ---"
let dropdownLabelReleased = "--- Released ---"
// Used for the DocsOverview and collapsible navigation
-let languageManual = version => {
- [
- ("Overview", `/docs/manual/${version}/introduction`),
- ("Language Features", `/docs/manual/${version}/overview`),
- ("JS Interop", `/docs/manual/${version}/embed-raw-javascript`),
- ("Build System", `/docs/manual/${version}/build-overview`),
- ]
-}
+let languageManual = [
+ ("Overview", "/docs/manual/introduction"),
+ ("Language Features", "/docs/manual/overview"),
+ ("JS Interop", "/docs/manual/embed-raw-javascript"),
+ ("Build System", "/docs/manual/build-overview"),
+]
let tools = [("Syntax Lookup", "/syntax-lookup")]
diff --git a/apps/docs/src/common/Sitemap.res b/apps/docs/src/common/Sitemap.res
new file mode 100644
index 000000000..2dfacc6b1
--- /dev/null
+++ b/apps/docs/src/common/Sitemap.res
@@ -0,0 +1,81 @@
+let defaultBaseUrl = "https://rescript-lang.org"
+
+let normalizeBaseUrl = baseUrl => {
+ let trimmed = baseUrl->String.trim
+
+ let baseUrl = if trimmed === "" {
+ defaultBaseUrl
+ } else {
+ trimmed
+ }
+
+ if baseUrl->String.endsWith("/") {
+ baseUrl->String.slice(~start=0, ~end=baseUrl->String.length - 1)
+ } else {
+ baseUrl
+ }
+}
+
+let normalizePath = path => {
+ let trimmed = path->String.trim
+
+ if trimmed === "" || trimmed === "/" {
+ "/"
+ } else if trimmed->String.startsWith("/") {
+ trimmed
+ } else {
+ "/" ++ trimmed
+ }
+}
+
+let escapeXml = value =>
+ value
+ ->String.replaceAll("&", "&")
+ ->String.replaceAll("<", "<")
+ ->String.replaceAll(">", ">")
+ ->String.replaceAll("\"", """)
+ ->String.replaceAll("'", "'")
+
+let normalizePaths = paths =>
+ paths
+ ->Array.map(normalizePath)
+ ->Array.toSorted(String.compare)
+ ->Array.reduce([], (acc, path) => {
+ if acc->Array.includes(path) {
+ acc
+ } else {
+ acc->Array.push(path)
+ acc
+ }
+ })
+
+let withTrailingSlash = path => {
+ if path === "/" || path->String.endsWith("/") {
+ path
+ } else {
+ path ++ "/"
+ }
+}
+
+let renderUrl = (~baseUrl, path) => {
+ let loc = baseUrl ++ path->withTrailingSlash
+
+ `
+ ${loc->escapeXml}
+ `
+}
+
+let render = (~baseUrl, paths) => {
+ let baseUrl = normalizeBaseUrl(baseUrl)
+ let urls =
+ paths
+ ->normalizePaths
+ ->Array.map(path => renderUrl(~baseUrl, path))
+ ->Array.join("\n")
+
+ `
+
+${urls}
+
+`
+}
diff --git a/apps/docs/src/common/Url.res b/apps/docs/src/common/Url.res
index fb31e28cd..7f56de3fc 100644
--- a/apps/docs/src/common/Url.res
+++ b/apps/docs/src/common/Url.res
@@ -1,46 +1,6 @@
-type version =
- | Latest
- | Next
- | NoVersion
- | Version(string)
-
-/*
- Example 1:
- Url: "/docs/manual/latest/advanced/introduction"
-
- Results in:
- fullpath: ["docs", "manual", "latest", "advanced", "introduction"]
- base: ["docs", "manual"]
- version: Latest
- pagepath: ["advanced", "introduction"]
- */
-
-/*
- Example 2:
- Url: "/apis/"
-
- Results in:
- fullpath: ["apis"]
- base: ["apis"]
- version: NoVersion
- pagepath: []
- */
-
-/*
- Example 3:
- Url: "/apis/javascript/v7.1.1/node"
-
- Results in:
- fullpath: ["apis", "javascript", "v7.1.1", "node"]
- base: ["apis", "javascript"]
- version: Version("v7.1.1"),
- pagepath: ["node"]
- */
-
type t = {
fullpath: array,
base: array,
- version: version,
pagepath: array,
}
@@ -56,29 +16,13 @@ let prettyString = (str: string) => {
}
let parse = (route: string): t => {
- let fullpath = route->String.split("/")->Array.filter(s => s !== "")
- let foundVersionIndex = Array.findIndex(fullpath, chunk => {
- RegExp.test(/latest|next|v\d+(\.\d+)?(\.\d+)?/, chunk)
- })
+ let routePath = route->String.split("/")->Array.filter(s => s !== "")
- let (version, base, pagepath) = if foundVersionIndex == -1 {
- (NoVersion, fullpath, [])
- } else {
- let version = switch fullpath[foundVersionIndex] {
- | Some(version) if version === Constants.versions.next => Next
- | Some(version) if version === Constants.versions.latest => Latest
- | Some("latest") => Latest // still used for React docs
- | Some(v) => Version(v)
- | None => NoVersion
- }
- (
- version,
- fullpath->Array.slice(~start=0, ~end=foundVersionIndex),
- fullpath->Array.slice(~start=foundVersionIndex + 1, ~end=Array.length(fullpath)),
- )
+ {
+ fullpath: routePath,
+ base: routePath,
+ pagepath: [],
}
-
- {fullpath, base, version, pagepath}
}
@unboxed
@@ -95,13 +39,6 @@ let getVersionFromStorage = (key: storageKey) => {
}
}
-let getVersionString = url =>
- switch url.version {
- | Next => Constants.versions.next
- | Latest | NoVersion => Constants.versions.latest
- | Version(version) => version
- }
-
let normalizePath = string => {
string->String.replaceRegExp(/\/$/, "")->String.toLocaleLowerCase
}
@@ -116,3 +53,15 @@ let normalizeAnchor = string => {
->String.replaceAllRegExp(/[^a-zA-Z0-9-]/g, "")
->String.toLocaleLowerCase
}
+
+type anchorIdState = Dict.t
+
+let makeAnchorIdState = () => Dict.make()
+
+let makeUniqueAnchorId = (~state, ~title) => {
+ let baseId = title->normalizeAnchor
+ let count = state->Dict.get(baseId)->Option.getOr(0)
+ state->Dict.set(baseId, count + 1)
+
+ count === 0 ? baseId : `${baseId}-${count->Int.toString}`
+}
diff --git a/apps/docs/src/common/Url.resi b/apps/docs/src/common/Url.resi
index afbeb91c2..a8954e9a5 100644
--- a/apps/docs/src/common/Url.resi
+++ b/apps/docs/src/common/Url.resi
@@ -1,13 +1,6 @@
-type version =
- | Latest
- | Next
- | NoVersion
- | Version(string)
-
type t = {
fullpath: array,
base: array,
- version: version,
pagepath: array,
}
@@ -29,8 +22,12 @@ type storageKey =
let getVersionFromStorage: storageKey => option
-let getVersionString: t => string
-
let normalizePath: string => string
let normalizeAnchor: string => string
+
+type anchorIdState
+
+let makeAnchorIdState: unit => anchorIdState
+
+let makeUniqueAnchorId: (~state: anchorIdState, ~title: string) => string
diff --git a/apps/docs/src/components/Markdown.res b/apps/docs/src/components/Markdown.res
index 247a5d74f..6de1a22ca 100644
--- a/apps/docs/src/components/Markdown.res
+++ b/apps/docs/src/components/Markdown.res
@@ -116,7 +116,6 @@ module Anchor = {
title=?title
className="scroll-mt-30 invisible text-gray-60 opacity-50 hover:opacity-100 hover:text-gray-60 hover:cursor-pointer group-hover:visible"
href={"#" ++ id}
- id={id}
>
children
+ let make = (~id=?, ~title=?, ~children) =>
+ children
}
module H2 = {
@@ -136,7 +136,7 @@ module H2 = {
// Children may not be a string
<>
-
+
children
+
children
+
children
children
diff --git a/apps/docs/src/components/Markdown.resi b/apps/docs/src/components/Markdown.resi
index 6234ea9dd..4c42ad8ff 100644
--- a/apps/docs/src/components/Markdown.resi
+++ b/apps/docs/src/components/Markdown.resi
@@ -40,7 +40,7 @@ module Anchor: {
module H1: {
@react.component
- let make: (~children: React.element) => React.element
+ let make: (~id: string=?, ~title: string=?, ~children: React.element) => React.element
}
module H2: {
diff --git a/apps/docs/src/components/MarkdownComponents.res b/apps/docs/src/components/MarkdownComponents.res
index 67a5a272a..145d118c7 100644
--- a/apps/docs/src/components/MarkdownComponents.res
+++ b/apps/docs/src/components/MarkdownComponents.res
@@ -27,7 +27,7 @@ type t = {
/* Common markdown elements */
p?: P.props => React.element,
li?: Li.props => React.element,
- h1?: H1.props => React.element,
+ h1?: H1.props => React.element,
h2?: H2.props => React.element,
h3?: H3.props => React.element,
h4?: H4.props => React.element,
diff --git a/apps/docs/src/components/Meta.res b/apps/docs/src/components/Meta.res
index 4985bdb18..bcaa140d8 100644
--- a/apps/docs/src/components/Meta.res
+++ b/apps/docs/src/components/Meta.res
@@ -72,8 +72,8 @@ let make = (
- // Docsearch meta tags
-
+
+ Array.join(",")} />
// Robots meta tag
diff --git a/apps/docs/src/components/Search.res b/apps/docs/src/components/Search.res
index b9ccbb103..42c5e7c41 100644
--- a/apps/docs/src/components/Search.res
+++ b/apps/docs/src/components/Search.res
@@ -1,108 +1,318 @@
-let apiKey = "a2485ef172b8cd82a2dfa498d551399b"
-let indexName = "rescript-lang"
-let appId = "S32LNEY41T"
-
type state = Active | Inactive
-let hit = ({hit, children}: DocSearch.hitComponent) => {
- let toTitle = str => str->String.charAt(0)->String.toUpperCase ++ String.slice(str, ~start=1)
-
- let description = switch hit.url
- ->String.split("/")
- ->Array.slice(~start=1)
- ->List.fromArray {
- | list{"blog" as r | "community" as r, ..._} => r->toTitle
- | list{"docs", doc, version, ...rest} =>
- let path = rest->List.toArray
-
- let info =
- path
- ->Array.slice(~start=0, ~end=Array.length(path) - 1)
- ->Array.map(path =>
- switch path {
- | "api" => "API"
- | other => toTitle(other)
- }
- )
+let unavailableText = "Search unavailable"
+let unavailableLabel = "Search unavailable for this build"
- [doc->toTitle, version->toTitle]->Array.concat(info)->Array.join(" / ")
- | _ => ""
+let toRelativeSiteUrl = (url: string, ~siteUrl: string): string => {
+ let normalizedSiteUrl = siteUrl->String.replaceRegExp(RegExp.fromString("/+$", ~flags=""), "")
+ if normalizedSiteUrl !== "" && String.startsWith(url, normalizedSiteUrl) {
+ let relativePath = String.slice(url, ~start=String.length(normalizedSiteUrl))
+ if relativePath === "" {
+ "/"
+ } else if String.startsWith(relativePath, "/") {
+ relativePath
+ } else {
+ "/" ++ relativePath
+ }
+ } else {
+ url
}
+}
- let isDeprecated = hit.deprecated->Option.isSome
- let deprecatedBadge = isDeprecated
- ?
- {"Deprecated"->React.string}
-
- : React.null
-
-
-
- {deprecatedBadge}
- {description->React.string}
-
- children
-
+type apiNamespace = StdlibApi | BeltApi
+
+let apiNamespaceForUrl = (url: string): option =>
+ if url->String.includes("/docs/manual/api/stdlib/") {
+ Some(StdlibApi)
+ } else if url->String.includes("/docs/manual/api/belt/") {
+ Some(BeltApi)
+ } else {
+ None
+ }
+
+let stripCaseInsensitivePrefix = (value: string, prefix: string): string => {
+ if (
+ prefix->String.length > 0 &&
+ value->String.toLowerCase->String.startsWith(prefix->String.toLowerCase)
+ ) {
+ String.slice(value, ~start=String.length(prefix))
+ } else {
+ value
+ }
}
-let transformItems = (items: DocSearch.transformItems) => {
- items
- ->Array.filterMap(item => {
- let url = try WebAPI.URL.make(~url=item.url)->Some catch {
- | JsExn(obj) =>
- Console.error2(`Failed to parse URL ${item.url}`, obj)
- None
- }
- switch url {
- | Some({pathname, hash}) =>
- RegExp.test(/v(8|9|10|11)\./, pathname)
- ? None
- : {
- // DocSearch internally calls .replace() on hierarchy.lvl1, so we must
- // provide a fallback for items where lvl1 is null to prevent crashes
- let hierarchy = item.hierarchy
- let lvl0 = hierarchy.lvl0->Nullable.toOption->Option.getOr("")
- let lvl1 = hierarchy.lvl1->Nullable.toOption->Option.getOr(lvl0)
- Some({
- ...item,
- deprecated: pathname->String.includes("api/js") ||
- pathname->String.includes("api/core")
- ? Some("Deprecated")
- : None,
- url: pathname->String.replace("/v12.0.0/", "/") ++ hash,
- hierarchy: {
- ...hierarchy,
- lvl0: Nullable.make(lvl0),
- lvl1: Nullable.make(lvl1),
- },
- })
- }
+let baseApiModuleName = (moduleName: string): string =>
+ moduleName->stripCaseInsensitivePrefix("Stdlib.")->stripCaseInsensitivePrefix("Belt.")
- | None => None
+let apiGroupName = (hit: DocSearch.docSearchHit): option =>
+ switch (apiNamespaceForUrl(hit.url), hit.hierarchy.lvl0->Nullable.toOption) {
+ | (Some(StdlibApi), Some(moduleName)) if moduleName !== "" =>
+ Some(moduleName->stripCaseInsensitivePrefix("Stdlib."))
+ | (Some(BeltApi), Some(moduleName)) if moduleName !== "" =>
+ Some(`Belt.${moduleName->baseApiModuleName}`)
+ | _ => None
+ }
+
+let normalizeHitUrls = (items: array, ~siteUrl: string) =>
+ items->Array.map(hit => {
+ let url = toRelativeSiteUrl(hit.url, ~siteUrl)
+ let urlWithoutAnchor =
+ hit.url_without_anchor
+ ->Nullable.toOption
+ ->Option.getOr(hit.url->String.split("#")->Array.get(0)->Option.getOr(hit.url))
+ let url_without_anchor = toRelativeSiteUrl(urlWithoutAnchor, ~siteUrl)->Nullable.make
+ let hierarchy = switch hit->apiGroupName {
+ | Some(lvl0) => {...hit.hierarchy, lvl0: Nullable.make(lvl0)}
+ | None => hit.hierarchy
}
+ {...hit, url, url_without_anchor, hierarchy}
})
- // Sort deprecated items to the end
- ->Array.toSorted((a, b) => {
- switch (a.deprecated, b.deprecated) {
- | (Some(_), None) => 1. // a is deprecated, b is not - put a after b
- | (None, Some(_)) => -1. // a is not deprecated, b is - put a before b
- | _ => 0.
+
+let navigator = (~siteUrl: string): DocSearch.navigator => {
+ navigate: ({itemUrl}) => {
+ ReactRouter.navigate(toRelativeSiteUrl(itemUrl, ~siteUrl))
+ },
+}
+
+let getSubtitle: DocSearch.docSearchHit => option = %raw(`
+ function(hit) {
+ var type = hit.type;
+ if (type && type !== 'lvl1' && type !== 'lvl0') {
+ var raw = hit.hierarchy;
+ if (raw && raw.lvl1) return raw.lvl1;
}
- })
- ->Array.toSorted((a, b) => {
- switch (a.url->String.includes("api/stdlib"), b.url->String.includes("api/stdlib")) {
- | (true, false) => -1. // a is a stdlib doc, b is not - put a before b
- | (false, true) => 1. // a is not a stdlib doc, b is - put a after b
- | _ => 0. // both same API status - maintain original order
+ return undefined;
+ }
+`)
+
+let highlightedValue = (value: Nullable.t): option =>
+ value->Nullable.toOption->Option.map(value => value.value)
+
+let highlightedValueWithMarkup = (value: Nullable.t): option =>
+ switch highlightedValue(value) {
+ | Some(value) if value->String.includes("") => Some(value)
+ | _ => None
+ }
+
+let highlightedHierarchyValue = (
+ hierarchy: DocSearch.highlightedHierarchy,
+ type_: DocSearch.contentType,
+): option =>
+ switch type_ {
+ | Lvl0 => hierarchy.lvl0->highlightedValue
+ | Lvl1 => hierarchy.lvl1->highlightedValue
+ | Lvl2 => hierarchy.lvl2->highlightedValue
+ | Lvl3 => hierarchy.lvl3->highlightedValue
+ | Lvl4 => hierarchy.lvl4->highlightedValue
+ | Lvl5 => hierarchy.lvl5->highlightedValue
+ | Lvl6 => hierarchy.lvl6->highlightedValue
+ | Content => None
+ }
+
+let highlightedHierarchyValueWithMarkup = (
+ hierarchy: DocSearch.highlightedHierarchy,
+ type_: DocSearch.contentType,
+): option =>
+ switch type_ {
+ | Lvl0 => hierarchy.lvl0->highlightedValueWithMarkup
+ | Lvl1 => hierarchy.lvl1->highlightedValueWithMarkup
+ | Lvl2 => hierarchy.lvl2->highlightedValueWithMarkup
+ | Lvl3 => hierarchy.lvl3->highlightedValueWithMarkup
+ | Lvl4 => hierarchy.lvl4->highlightedValueWithMarkup
+ | Lvl5 => hierarchy.lvl5->highlightedValueWithMarkup
+ | Lvl6 => hierarchy.lvl6->highlightedValueWithMarkup
+ | Content => None
+ }
+
+let firstMarkedText = (html: string): option => {
+ switch RegExp.exec(/([^<]+)<\/mark>/, html) {
+ | Some(result) =>
+ let matches = RegExp.Result.matches(result)
+ switch matches[0] {
+ | Some(Some(markedText)) => Some(markedText)
+ | _ => None
}
- })
+ | None => None
+ }
+}
+
+let markTitlePrefix = (title: string, markedText: string): string => {
+ let markedLength = String.length(markedText)
+ if (
+ markedLength > 0 && title->String.toLowerCase->String.startsWith(markedText->String.toLowerCase)
+ ) {
+ let prefix = String.slice(title, ~start=0, ~end=markedLength)
+ let suffix = String.slice(title, ~start=markedLength)
+ `${prefix}${suffix}`
+ } else {
+ title
+ }
+}
+
+let stripApiModulePrefix = (markedText: string, moduleName: string): string => {
+ let moduleName = moduleName->baseApiModuleName
+ markedText
+ ->stripCaseInsensitivePrefix(`Stdlib.${moduleName}.`)
+ ->stripCaseInsensitivePrefix(`Belt.${moduleName}.`)
+ ->stripCaseInsensitivePrefix(`${moduleName}.`)
+}
+
+let getSnippetContent = (hit: DocSearch.docSearchHit): option =>
+ switch hit._snippetResult {
+ | Some(snippetResult) => snippetResult.content->highlightedValue
+ | None => None
+ }
+
+let getApiTitle = (hit: DocSearch.docSearchHit): option => {
+ if hit.url->String.includes("/docs/manual/api/") {
+ switch (hit.hierarchy.lvl0->Nullable.toOption, hit.hierarchy.lvl1->Nullable.toOption) {
+ | (Some(moduleName), Some(valueName)) if moduleName !== "" && valueName !== "" =>
+ let title = valueName
+ switch hit->getSnippetContent->Option.flatMap(firstMarkedText) {
+ | Some(markedText) =>
+ Some(markTitlePrefix(title, stripApiModulePrefix(markedText, moduleName)))
+ | None => Some(title)
+ }
+ | _ => None
+ }
+ } else {
+ None
+ }
+}
+
+let getHighlightedTitle = (hit: DocSearch.docSearchHit): string => {
+ let highlightedHierarchy =
+ hit._highlightResult->Option.flatMap(highlightResult =>
+ highlightResult.hierarchy->Nullable.toOption
+ )
+ let highlightedTitleWithMarkup = highlightedHierarchy->Option.flatMap(hierarchy =>
+ switch hit.type_ {
+ | Lvl0 | Lvl1 => None
+ | _ => highlightedHierarchyValueWithMarkup(hierarchy, hit.type_)
+ }
+ )
+
+ switch highlightedTitleWithMarkup {
+ | Some(title) => title
+ | None =>
+ switch highlightedHierarchy->Option.flatMap(hierarchy =>
+ hierarchy.lvl1->highlightedValueWithMarkup
+ ) {
+ | Some(title) => title
+ | None =>
+ switch getApiTitle(hit) {
+ | Some(title) => title
+ | None =>
+ switch highlightedHierarchy->Option.flatMap(hierarchy =>
+ highlightedHierarchyValue(hierarchy, hit.type_)
+ ) {
+ | Some(title) => title
+ | None => hit.hierarchy.lvl1->Nullable.toOption->Option.getOr("")
+ }
+ }
+ }
+ }
+}
+
+let markdownToHtml = (text: string): string =>
+ text
+ // Strip stray backslashes from MDX processing
+ ->String.replaceRegExp(RegExp.fromString("^\\\\\\s+", ~flags=""), "")
+ ->String.replaceRegExp(RegExp.fromString("\\\\\\s+", ~flags="g"), " ")
+ ->String.replaceRegExp(
+ RegExp.fromString("See\\s+\\[([^\\]]+)\\]\\([^)]*\\)\\s+on MDN\\.?", ~flags="g"),
+ "",
+ )
+ ->String.replaceRegExp(RegExp.fromString("See\\s+\\S+\\s+on MDN\\.?", ~flags="g"), "")
+ ->String.replaceRegExp(RegExp.fromString("\\[([^\\]]+)\\]\\([^)]*\\)", ~flags="g"), "$1")
+ ->String.replaceRegExp(RegExp.fromString("\\x60([^\\x60]+)\\x60", ~flags="g"), "$1")
+ ->String.replaceRegExp(
+ RegExp.fromString("\\*\\*([^*]+)\\*\\*", ~flags="g"),
+ "$1",
+ )
+ ->String.replaceRegExp(RegExp.fromString("\\*([^*]+)\\*", ~flags="g"), "$1")
+ ->String.replaceRegExp(RegExp.fromString("\\n{2,}", ~flags="g"), "
")
+ ->String.replaceRegExp(RegExp.fromString("\\n", ~flags="g"), " ")
+ ->String.trim
+
+let isChildHit = (hit: DocSearch.docSearchHit) =>
+ switch hit.type_ {
+ | Lvl2 | Lvl3 | Lvl4 | Lvl5 | Lvl6 | Content => true
+ | Lvl0 | Lvl1 => hit.url->String.includes("#")
+ }
+
+let getContentHtml = (hit: DocSearch.docSearchHit): option =>
+ switch getSnippetContent(hit) {
+ | Some(content) => Some(content->markdownToHtml)
+ | None => hit.content->Nullable.toOption->Option.map(markdownToHtml)
+ }
+
+let hitComponent = ({hit, children: _}: DocSearch.hitComponent): React.element => {
+ let titleHtml = getHighlightedTitle(hit)
+ let subtitle = getSubtitle(hit)
+ let contentHtml = getContentHtml(hit)
+ let isChild = isChildHit(hit)
+
+
+
+ {isChild ?
+}
+
+module ErrorBoundary = {
+ @react.component
+ let make = (~children: React.element, ~onClose: unit => unit) => {
+
+
+
+ {React.string(unavailableText)}
+
+
+ }
+ >
+ children
+
+ }
}
@react.component
let make = () => {
let (state, setState) = React.useState(_ => Inactive)
+ let algoliaConfig = Env.algoliaPublicConfig
+
+ let deactivateSearch = () => {
+ switch WebAPI.Document.querySelector(document, "body") {
+ | Value(body) => WebAPI.DOMTokenList.remove(body.classList, "DocSearch--active")
+ | Null => ()
+ }
+ setState(_ => Inactive)
+ }
let handleCloseModal = () => {
let () = switch WebAPI.Document.querySelector(document, ".DocSearch-Modal") {
@@ -115,38 +325,41 @@ let make = () => {
})
| Null => setState(_ => Inactive)
}
- | Null => ()
+ | Null => deactivateSearch()
}
}
React.useEffect(() => {
- let isEditableTag = (el: WebAPI.DOMAPI.element) =>
- switch el.tagName {
- | "TEXTAREA" | "SELECT" | "INPUT" => true
- | _ => false
- }
+ switch algoliaConfig {
+ | None => None
+ | Some(_) =>
+ let isEditableTag = (el: WebAPI.DOMAPI.element) =>
+ switch el.tagName {
+ | "TEXTAREA" | "SELECT" | "INPUT" => true
+ | _ => false
+ }
- let focusSearch = (e: WebAPI.UIEventsAPI.keyboardEvent) => {
- switch document.activeElement {
- | Value(el)
- if el->isEditableTag || (Obj.magic(el): WebAPI.DOMAPI.htmlElement).isContentEditable => ()
- | _ =>
- setState(_ => Active)
- WebAPI.KeyboardEvent.preventDefault(e)
+ let focusSearch = (e: WebAPI.UIEventsAPI.keyboardEvent) => {
+ switch document.activeElement {
+ | Value(el)
+ if el->isEditableTag || (Obj.magic(el): WebAPI.DOMAPI.htmlElement).isContentEditable => ()
+ | _ =>
+ setState(_ => Active)
+ WebAPI.KeyboardEvent.preventDefault(e)
+ }
}
- }
- let handleGlobalKeyDown = (e: WebAPI.UIEventsAPI.keyboardEvent) => {
- switch e.key {
- | "/" => focusSearch(e)
- | "k" if e.ctrlKey || e.metaKey => focusSearch(e)
- | "Escape" => handleCloseModal()
- | _ => ()
+ let handleGlobalKeyDown = (e: WebAPI.UIEventsAPI.keyboardEvent) => {
+ switch e.key {
+ | "/" => focusSearch(e)
+ | "k" if e.ctrlKey || e.metaKey => focusSearch(e)
+ | _ => ()
+ }
}
+ WebAPI.Window.addEventListener(window, Keydown, handleGlobalKeyDown)
+ Some(() => WebAPI.Window.removeEventListener(window, Keydown, handleGlobalKeyDown))
}
- WebAPI.Window.addEventListener(window, Keydown, handleGlobalKeyDown)
- Some(() => WebAPI.Window.removeEventListener(window, Keydown, handleGlobalKeyDown))
- }, [setState])
+ }, [algoliaConfig])
let onClick = _ => {
setState(_ => Active)
@@ -156,34 +369,56 @@ let make = () => {
handleCloseModal()
}, [setState])
- <>
+ switch algoliaConfig {
+ | None =>
- {switch state {
- | Active =>
- switch ReactDOM.querySelector("body") {
- | Some(element) =>
- ReactDOM.createPortal(
- Float.toInt}
- transformItems={transformItems}
- hitComponent=hit
- />,
- element,
- )
- | None => React.null
- }
- | Inactive => React.null
- }}
-
+ | Some({appId, indexName, searchApiKey}) =>
+ <>
+
+ {switch state {
+ | Active =>
+ switch ReactDOM.querySelector("body") {
+ | Some(element) =>
+ ReactDOM.createPortal(
+
+ normalizeHitUrls(items, ~siteUrl=Env.root_url)}
+ hitComponent
+ onClose
+ initialScrollY={window.scrollY->Float.toInt}
+ searchParameters={
+ distinct: 3,
+ hitsPerPage: 20,
+ attributesToSnippet: ["content:9999"],
+ }
+ />
+ ,
+ element,
+ )
+ | None => React.null
+ }
+ | Inactive => React.null
+ }}
+
+ }
}
diff --git a/apps/docs/src/layouts/CommunityLayout.res b/apps/docs/src/layouts/CommunityLayout.res
index d95cc201d..ec8e213e8 100644
--- a/apps/docs/src/layouts/CommunityLayout.res
+++ b/apps/docs/src/layouts/CommunityLayout.res
@@ -24,6 +24,7 @@ let make = (~children, ~categories, ~entries) => {
/>}
sidebarState=(isSidebarOpen, setSidebarOpen)
theme=#Reason
+ docSearchLvl0="Community"
>
children
diff --git a/apps/docs/src/layouts/DocsLayout.res b/apps/docs/src/layouts/DocsLayout.res
index 82901e7db..e319484c8 100644
--- a/apps/docs/src/layouts/DocsLayout.res
+++ b/apps/docs/src/layouts/DocsLayout.res
@@ -8,6 +8,7 @@ let make = (
~activeToc: option=?,
~categories: array,
~components=MarkdownComponents.default,
+ ~docSearchLvl0=?,
~theme=#Reason,
~children,
) => {
@@ -24,7 +25,9 @@ let make = (
let sidebar =
+
children
}
diff --git a/apps/docs/src/layouts/SidebarLayout.res b/apps/docs/src/layouts/SidebarLayout.res
index 85e69f4f0..00bbb71cf 100644
--- a/apps/docs/src/layouts/SidebarLayout.res
+++ b/apps/docs/src/layouts/SidebarLayout.res
@@ -250,6 +250,7 @@ let make = (
~sidebar: React.element,
~rightSidebar: option=?,
~categories: option>=?,
+ ~docSearchLvl0: option=?,
~children,
) => {
let location = ReactRouter.useLocation()
@@ -303,8 +304,15 @@ let make = (
sidebar
+ {switch docSearchLvl0 {
+ | Some(value) =>
+
+ {React.string(value)}
+
+ | None => React.null
+ }}
children
pagination
diff --git a/apps/docs/src/layouts/SidebarLayout.resi b/apps/docs/src/layouts/SidebarLayout.resi
index 6498b5a16..039316094 100644
--- a/apps/docs/src/layouts/SidebarLayout.resi
+++ b/apps/docs/src/layouts/SidebarLayout.resi
@@ -66,5 +66,6 @@ let make: (
~sidebar: React.element,
~rightSidebar: React.element=?,
~categories: array=?,
+ ~docSearchLvl0: string=?,
~children: React.element,
) => React.element
diff --git a/apps/docs/src/markdown/Mdx.res b/apps/docs/src/markdown/Mdx.res
index cadf676c5..dbb9bc9c5 100644
--- a/apps/docs/src/markdown/Mdx.res
+++ b/apps/docs/src/markdown/Mdx.res
@@ -188,18 +188,17 @@ let remarkLinkPlugin = makePlugin(_options => (tree, vfile) => remarkLinkPlugin(
// converts the inner text of headings to kebab-case IDs
let anchorLinkPlugin = (tree, _vfile) => {
+ let headingIds = Url.makeAnchorIdState()
+
visit(tree, "heading", node => {
let planText = childrenToString(node)
- let nodeData = switch node["data"] {
- | Some(data) => data
- | None => {
- "hProperties": {
- "id": planText->Url.normalizeAnchor,
- "title": planText,
- },
- }
+ let id = Url.makeUniqueAnchorId(~state=headingIds, ~title=planText)
+ node["data"] = {
+ "hProperties": {
+ "id": id,
+ "title": planText,
+ },
}
- node["data"] = nodeData
})
}
diff --git a/apps/docs/src/markdown/TocUtils.res b/apps/docs/src/markdown/TocUtils.res
index b09a83382..e070b3529 100644
--- a/apps/docs/src/markdown/TocUtils.res
+++ b/apps/docs/src/markdown/TocUtils.res
@@ -1,15 +1,17 @@
let buildEntries = (raw: string) => {
let markdownTree = Mdast.fromMarkdown(raw)
- let tocResult = Mdast.toc(markdownTree, {maxDepth: 2})
+ let headingIds = Url.makeAnchorIdState()
+ let entries: array = []
- let headers = Dict.make()
- Mdast.reduceHeaders(tocResult.map, headers)
-
- headers
- ->Dict.toArray
- ->Array.map(((header, url)): TableOfContents.entry => {
- header,
- href: (url :> string),
+ Mdast.visit(markdownTree, "heading", node => {
+ if node["depth"] <= 2 {
+ let header = Mdast.toString(node)
+ entries->Array.push({
+ header,
+ href: "#" ++ Url.makeUniqueAnchorId(~state=headingIds, ~title=header),
+ })
+ }
})
- ->Array.slice(~start=2)
+
+ entries->Array.slice(~start=2)
}
diff --git a/apps/docs/styles/_docsearch.css b/apps/docs/styles/_docsearch.css
index ac8c167b7..ba5f02688 100644
--- a/apps/docs/styles/_docsearch.css
+++ b/apps/docs/styles/_docsearch.css
@@ -137,17 +137,17 @@
@apply hidden;
}
+.DocSearch-Clear {
+ @apply hidden;
+}
+
.DocSearch-LoadingIndicator svg,
.DocSearch-MagnifierLabel svg {
@apply w-4 h-4;
}
.DocSearch-Cancel {
- font-size: 0;
- background-image: url("data:image/svg+xml,%3Csvg width='16' height='7' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M.506 6h3.931V4.986H1.736v-1.39h2.488V2.583H1.736V1.196h2.69V.182H.506V6ZM8.56 1.855h1.18C9.721.818 8.87.102 7.574.102c-1.276 0-2.21.705-2.205 1.762-.003.858.602 1.35 1.585 1.585l.634.159c.633.153.986.335.988.727-.002.426-.406.716-1.03.716-.64 0-1.1-.295-1.14-.878h-1.19c.03 1.259.931 1.91 2.343 1.91 1.42 0 2.256-.68 2.259-1.745-.003-.969-.733-1.483-1.744-1.71l-.523-.125c-.506-.117-.93-.304-.92-.722 0-.375.332-.65.934-.65.588 0 .949.267.994.724ZM15.78 2.219C15.618.875 14.6.102 13.254.102c-1.537 0-2.71 1.086-2.71 2.989 0 1.898 1.153 2.989 2.71 2.989 1.492 0 2.392-.992 2.526-2.063l-1.244-.006c-.117.623-.606.98-1.262.98-.883 0-1.483-.656-1.483-1.9 0-1.21.591-1.9 1.492-1.9.673 0 1.159.389 1.253 1.028h1.244Z' fill='%2394a3b8'/%3E%3C/svg%3E") !important;
- background-size: 57.1428571429% auto;
- @apply w-9 h-7 bg-no-repeat bg-center appearance-none border border-gray-20
- rounded;
+ display: none !important;
}
/* Modal Dropdown */
@@ -273,8 +273,16 @@ svg.DocSearch-Hit-Select-Icon {
@apply text-14 text-gray-60;
}
+.DocSearch-Hit-subtitle {
+ @apply text-12 text-gray-40;
+}
+
.DocSearch-Hit-path {
- @apply text-12;
+ @apply text-14 text-gray-60;
+}
+
+.DocSearch-Hit-path code {
+ @apply bg-gray-10 text-black rounded-sm px-1 py-0.5 text-12 font-mono;
}
.DocSearch-Hit[aria-selected="true"] .DocSearch-Hit-title,
@@ -319,12 +327,40 @@ svg.DocSearch-Hit-Select-Icon {
/* Modal Footer */
.DocSearch-Footer {
- @apply flex flex-row-reverse flex-shrink-0 justify-between relative
- select-none w-full z-100 p-4;
+ border-top: 1px solid;
+ @apply flex flex-shrink-0 items-center justify-between relative
+ select-none w-full z-100 px-4 py-3 border-gray-20;
}
.DocSearch-Commands {
- display: none !important;
+ @apply flex items-center gap-3 list-none m-0 p-0;
+}
+
+.DocSearch-Commands li {
+ @apply flex items-center gap-1.5 text-12 text-gray-40;
+}
+
+.DocSearch-Commands-Key {
+ @apply inline-flex items-center justify-center w-5 h-5 rounded
+ border border-gray-20 bg-gray-5 text-11 text-gray-60 font-medium;
+}
+
+/* Swap "to close" / "to clear" based on whether the input has a query.
+ :placeholder-shown is true when the input is empty, false when it has text. */
+.DocSearch-Commands li:last-child .DocSearch-Label {
+ font-size: 0;
+}
+
+.DocSearch-Commands li:last-child .DocSearch-Label::after {
+ content: "to close";
+ font-size: 0.75rem;
+}
+
+.DocSearch-Modal:has(.DocSearch-Input:not(:placeholder-shown))
+ .DocSearch-Commands
+ li:last-child
+ .DocSearch-Label::after {
+ content: "to clear";
}
/* Responsive */
diff --git a/docs/superpowers/plans/2026-04-27-docsearch-crawler-indexing.md b/docs/superpowers/plans/2026-04-27-docsearch-crawler-indexing.md
new file mode 100644
index 000000000..d3449ddd8
--- /dev/null
+++ b/docs/superpowers/plans/2026-04-27-docsearch-crawler-indexing.md
@@ -0,0 +1,273 @@
+# DocSearch Crawler Indexing Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Convert PR #1231 from build-time Algolia write API indexing to DocSearch crawler-compatible static HTML while preserving the public DocSearch search UI.
+
+**Architecture:** Algolia owns indexing through the DocSearch crawler. The website build should generate only static HTML and existing static artifacts; it must not upload records or set index settings. Search runtime uses public DocSearch credentials, and crawl quality comes from stable `.DocSearch-content` containers, unique heading anchors, atomic paragraph/list content, docsearch meta tags, and crawler documentation.
+
+**Tech Stack:** ReScript v12, React 19, React Router v7 pre-rendering, MDX, `@docsearch/react` v4, Vitest browser mode with Playwright, Yarn 4.
+
+---
+
+## Context
+
+PR: https://github.com/rescript-lang/rescript-lang.org/pull/1231
+
+DocSearch requirement source: https://docsearch.algolia.com/docs/required-configuration/
+
+DocSearch crawler requirements that matter for this repo:
+
+- Use a static `DocSearch-content` class on the main textual content container.
+- Use heading selectors for `lvl1` through `lvl6`; every matched heading needs a unique `id` or `name`.
+- Searchable body content should be in atomic `` or `
` elements.
+- Optional `docsearch:*` meta tags can apply record attributes such as language and version.
+- Sitemap coverage is recommended so the crawler can find updated pages.
+
+## Recommended Approach
+
+Use the crawler-compliant HTML approach.
+
+Alternative 1, minimal revert, would only delete the write API script and leave the current HTML alone. That avoids code work but leaves crawl quality accidental and keeps known heading-id problems.
+
+Alternative 2, crawler-compliant HTML, removes write credentials and actively shapes the rendered HTML for DocSearch. This is the recommended path because it matches the DocSearch plan constraints and keeps the improved UI independent from indexing.
+
+Alternative 3, keep a local generator for validation only, would retain most of `SearchIndex.res` but stop uploading. That creates two sources of truth for ranking and records, so it should be avoided unless we later need a diagnostics-only script.
+
+## File Map
+
+Remove write API publishing:
+
+- Delete `scripts/generate_search_index.res`.
+- Delete `src/bindings/Algolia.res`.
+- Delete `src/common/SearchIndex.res`.
+- Delete `src/common/SearchIndex.resi`.
+- Delete `__tests__/SearchIndex_.test.res`.
+- Delete SearchIndex visual snapshots under `__tests__/__screenshots__/SearchIndex_.test.jsx/`.
+- Modify `package.json` and `yarn.lock` to remove `algoliasearch` and the `build:search-index` command.
+- Modify `.github/workflows/deploy.yml` to stop exporting private Algolia admin variables.
+- Modify `.gitignore` only if deleted generated script patterns leave a one-off entry unnecessary.
+
+Keep public DocSearch runtime:
+
+- Keep `@docsearch/react`.
+- Keep `src/bindings/DocSearch.res`.
+- Keep `src/components/Search.res`.
+- Keep public env handling in `src/bindings/Env.res`, but remove publisher-only config from `src/common/AlgoliaConfig.res`.
+- Keep `scripts/LogAlgoliaEnvStatus.res` and `src/common/AlgoliaEnvStatus.res` if the public-config warning remains useful.
+
+Make HTML crawler-compatible:
+
+- Modify `src/layouts/SidebarLayout.res` so docs/community/API pages expose `DocSearch-content` on the central ``.
+- Modify `app/routes/BlogArticle.res` so article body content is wrapped in an ``.
+- Modify `app/routes/SyntaxLookup.res` so syntax detail content is crawlable without indexing the whole interactive picker.
+- Modify `src/components/Markdown.res` to preserve H1 ids and remove duplicate ids from anchor-link icons.
+- Modify `src/markdown/Mdx.res` to generate collision-free heading ids.
+- Modify `src/markdown/TocUtils.res` if needed so sidebar links match collision-free rendered heading ids.
+- Modify `app/routes/ApiDocs.res` so programmatic API H1/H2 headings have unique ids that match crawl targets.
+- Modify `src/components/Meta.res` to emit DocSearch language/version meta tags from existing version constants.
+
+Add or adjust tests:
+
+- Add `__tests__/DocSearchCrawlerMarkup_.test.res` or extend existing layout tests.
+- Update `__tests__/AlgoliaConfig_.test.res` to remove publisher-only expectations.
+- Update `__tests__/AlgoliaEnvStatus_.test.res` if public env names change.
+- Update `__tests__/Search_.test.res` for same-origin absolute crawler URLs and empty `siteUrl` behavior.
+- Update or remove generated screenshots only after explicit snapshot approval.
+
+## Implementation Tasks
+
+### Task 1: Add crawler-markup regression coverage
+
+**Files:**
+
+- Modify: `__tests__/DocsLayout_.test.res`
+- Modify: `__tests__/MarkdownComponents_.test.res` or add `__tests__/DocSearchCrawlerMarkup_.test.res`
+- Modify: `__tests__/Search_.test.res`
+
+- [ ] Add a test that renders `` and asserts the central main element has `DocSearch-content`.
+- [ ] Add a test that renders `Markdown.H1` with an id and asserts the `` keeps that id.
+- [ ] Add a test that renders `Markdown.H2` and asserts exactly one element in the document has that heading id.
+- [ ] Add a search URL test for an empty `siteUrl`: `Search.toRelativeSiteUrl("https://rescript-lang.org/docs/manual/introduction", ~siteUrl="")` should return the original URL.
+- [ ] Add a search URL test for a normal same-origin crawler hit: absolute `https://rescript-lang.org/docs/manual/introduction#what-is-rescript` should normalize to `/docs/manual/introduction#what-is-rescript`.
+- [ ] Run `yarn build:res`.
+- [ ] Run `yarn vitest --browser.headless --run __tests__/DocsLayout_.test.jsx __tests__/MarkdownComponents_.test.jsx __tests__/Search_.test.jsx`.
+- [ ] Confirm the new tests fail for the expected reasons before implementation.
+
+### Task 2: Remove Algolia write API publishing
+
+**Files:**
+
+- Delete: `scripts/generate_search_index.res`
+- Delete: `src/bindings/Algolia.res`
+- Delete: `src/common/SearchIndex.res`
+- Delete: `src/common/SearchIndex.resi`
+- Delete: `__tests__/SearchIndex_.test.res`
+- Delete: `__tests__/__screenshots__/SearchIndex_.test.jsx/*`
+- Modify: `package.json`
+- Modify: `yarn.lock`
+- Modify: `.github/workflows/deploy.yml`
+- Modify: `.gitignore`
+- Modify: `src/common/AlgoliaConfig.res`
+- Modify: `__tests__/AlgoliaConfig_.test.res`
+
+- [ ] Remove `build:search-index` from `package.json`.
+- [ ] Restore `build:update-index` to only generate LLM files and the blog feed:
+
+```json
+"build:update-index": "yarn build:generate-llms && node _scripts/generate_feed.mjs > public/blog/feed.xml"
+```
+
+- [ ] Keep `build` and `prepare` pointed at `build:update-index`; they should not invoke any Algolia uploader.
+- [ ] Remove the `algoliasearch` dependency with Yarn so `package.json` and `yarn.lock` stay consistent.
+- [ ] Remove `publisherConfig`, `missingPublisherVars`, and `publisherConfigFrom` from `AlgoliaConfig.res`.
+- [ ] Update `AlgoliaConfig_.test.res` to cover only public DocSearch config.
+- [ ] In `.github/workflows/deploy.yml`, remove `ALGOLIA_ADMIN_API_KEY_DEV`, `ALGOLIA_ADMIN_API_KEY_PROD`, and all `ALGOLIA_*` private exports.
+- [ ] Replace the derived basename flow with direct public variables:
+
+```yaml
+VITE_ALGOLIA_APP_ID: ${{ vars.VITE_ALGOLIA_APP_ID }}
+VITE_ALGOLIA_INDEX_NAME: ${{ vars.VITE_ALGOLIA_INDEX_NAME }}
+VITE_ALGOLIA_SEARCH_API_KEY: ${{ vars.VITE_ALGOLIA_SEARCH_API_KEY }}
+```
+
+- [ ] Remove `.gitignore` entries that only existed for deleted generated Algolia publishing files.
+- [ ] Run `yarn install --immutable` or the repository-approved Yarn flow after dependency removal.
+- [ ] Run `yarn build:res`.
+
+### Task 3: Keep the DocSearch UI, but make URL handling crawler-safe
+
+**Files:**
+
+- Modify: `src/components/Search.res`
+- Modify: `src/bindings/DocSearch.res`
+- Modify: `src/bindings/Env.res`
+- Modify: `__tests__/Search_.test.res`
+
+- [ ] Keep the custom hit component and URL normalization, because crawler hits can be absolute URLs.
+- [ ] Guard `toRelativeSiteUrl` so an empty `siteUrl` never matches every URL.
+- [ ] Treat `Env.root_url` as absent when `VITE_DEPLOYMENT_URL` is `Some("")`, or keep the guard entirely inside `Search.toRelativeSiteUrl`.
+- [ ] Do not move ranking or crawler record settings into the client; DocSearch crawler/dashboard owns index settings.
+- [ ] Keep `searchParameters` only for UI query behavior, such as `hitsPerPage`, snippets, distinct, and optional facet filters.
+- [ ] Run `yarn vitest --browser.headless --run __tests__/Search_.test.jsx`.
+
+### Task 4: Add DocSearch-content containers
+
+**Files:**
+
+- Modify: `src/layouts/SidebarLayout.res`
+- Modify: `app/routes/BlogArticle.res`
+- Modify: `app/routes/SyntaxLookup.res`
+- Modify: `__tests__/DocsLayout_.test.res`
+- Modify: `__tests__/BlogArticle_.test.res` if it already covers body markup
+- Modify: `__tests__/SyntaxLookup_.test.res` if it already covers detail pages
+
+- [ ] Add `DocSearch-content` to the central `` in `SidebarLayout.res`; this covers manual docs, React docs, guidelines, community pages, API overview, and API detail pages.
+- [ ] Wrap blog article body content in an `article` with `DocSearch-content markdown-body`.
+- [ ] For syntax lookup detail routes, put `DocSearch-content` on the detail body, not on the whole search-picker UI.
+- [ ] Keep visual class order stable and avoid changing layout styles.
+- [ ] Run the focused browser tests for touched layouts.
+
+### Task 5: Make heading anchors unique and crawler-readable
+
+**Files:**
+
+- Modify: `src/components/Markdown.res`
+- Modify: `src/markdown/Mdx.res`
+- Modify: `src/markdown/TocUtils.res`
+- Modify: `app/routes/ApiDocs.res`
+- Test: `__tests__/MarkdownComponents_.test.res`
+- Test: `__tests__/DocsLayout_.test.res`
+
+- [ ] Update `Markdown.H1.make` to accept optional `~id` and `~title` props and render the `id` on the `` when MDX provides it.
+- [ ] Update `Markdown.Anchor.make` so the decorative anchor icon does not render a second element with the same `id`.
+- [ ] Add a small heading-id helper in `src/markdown/` if needed so both MDX rendering and table-of-contents generation can use the same collision rules.
+- [ ] Update `Mdx.anchorLinkPlugin` so repeated headings get deterministic suffixes such as `usage`, `usage-1`, `usage-2`.
+- [ ] Update `TocUtils.buildEntries` to produce hrefs matching the rendered heading ids for duplicate headings.
+- [ ] Add ids to programmatic API H1 headings in `ApiDocs.res`; H2 ids already use `type-` and `value-`.
+- [ ] Run the heading and layout tests.
+
+### Task 6: Add DocSearch meta tags
+
+**Files:**
+
+- Modify: `src/components/Meta.res`
+- Modify: `src/common/Constants.res`
+- Test: `__tests__/MetaDescription_.test.res` or add a focused meta test if one exists for head tags
+
+- [ ] Add ``.
+- [ ] Add `Array.join(",")} />` using the current major version from `Constants.versions.latest`; include `latest` when the build serves the latest docs.
+- [ ] Keep the tag generic enough that older-version subdomain builds can provide their own version token through existing version constants.
+- [ ] Do not hardcode stale version text in route components.
+
+### Task 7: Document crawler-owned indexing
+
+**Files:**
+
+- Modify: `README.md` or add `docs/docsearch.md` if the repo maintainers prefer a focused doc.
+
+- [ ] Document that the DocSearch crawler owns indexing and index settings.
+- [ ] Document only public runtime variables:
+
+```txt
+VITE_ALGOLIA_APP_ID
+VITE_ALGOLIA_INDEX_NAME
+VITE_ALGOLIA_SEARCH_API_KEY
+```
+
+- [ ] Explicitly state that no admin/write key is used during builds or deployments.
+- [ ] Include the expected crawler selectors:
+
+```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"],
+}
+```
+
+- [ ] Note that production crawler start URLs and sitemap configuration live in the Algolia dashboard, not in the site build.
+
+### Task 8: Consider sitemap generation as a follow-up or include it if scope allows
+
+**Files if included now:**
+
+- Create: `scripts/generate_sitemap.res`
+- Modify: `package.json`
+- Modify: `public/robots.txt`
+- Modify: `react-router.config.mjs` only if route data is needed from there
+
+- [ ] Decide whether sitemap generation belongs in this PR or a follow-up.
+- [ ] If included, generate `public/sitemap.xml` or `out/sitemap.xml` from the same route sources used by React Router prerendering.
+- [ ] Include docs, API detail pages, community pages, syntax lookup detail pages, and blog posts.
+- [ ] Add `Sitemap: https://rescript-lang.org/sitemap.xml` to `public/robots.txt`.
+- [ ] Verify `yarn build` copies the sitemap into `out/`.
+
+## Final Verification
+
+- [ ] Run `yarn build:res`.
+- [ ] Run `yarn vitest --browser.headless --run`.
+- [ ] Run `yarn test`.
+- [ ] Run `yarn build`.
+- [ ] After `yarn build`, inspect representative generated HTML:
+
+```sh
+grep -R "DocSearch-content" out/docs/manual/introduction out/docs/react/introduction out/docs/manual/api/stdlib out/blog | head
+grep -R 'name="docsearch:version"' out/docs/manual/introduction | head
+grep -R 'id="javascript-interop"' out/docs/manual/introduction | head
+```
+
+- [ ] Confirm build logs do not invoke `generate_search_index` and do not require any `ALGOLIA_ADMIN_*` variables.
+- [ ] Do not update screenshots unless the user confirms snapshot updates.
+
+## Open Decision
+
+Sitemap generation is the only scope question. The DocSearch page calls it "nice to have" but also says it is key for crawler freshness. I would include markup and uploader removal in this PR, then add sitemap generation only if we want crawler discovery guarantees in the same change.
diff --git a/packages/shared/src/Icon.res b/packages/shared/src/Icon.res
index daac2bdf4..7830a805d 100644
--- a/packages/shared/src/Icon.res
+++ b/packages/shared/src/Icon.res
@@ -291,3 +291,84 @@ module Clipboard = {