Search indexing

Generate Markup Refine's static search index automatically with Astro or directly from any generated HTML tree.

Search is split into a framework-independent static HTML indexer and a thin Astro integration.DocsPage improves index quality by emitting structured metadata, but the indexer also supports ordinary generated HTML that does not use Astro or the docs components.

Automatic Astro indexing

Add markupRefineDocs() to the Astro config. After a static production build finishes, the integration receives Astro's resolved output directory and generates the search index there. It also reads Astro's configured base path for derived page URLs.

import { defineConfig } from "astro/config";
import { markupRefineDocs } from "markup-refine-lib/docs/integration";

export default defineConfig({
  integrations: [markupRefineDocs()],
});

Custom index location

The default output is search-index.json at the root of the generated site. A relativeoutputFile is resolved from the actual Astro output directory rather than from the process working directory.

export default defineConfig({
  integrations: [
    markupRefineDocs({
      outputFile: "assets/docs-search.json",
    }),
  ],
});

Use the generic builder without Astro

markup-refine-lib/docs/search exports the same builder directly. This path has no Astro dependency and can index any generated static HTML directory.

import { buildSearchIndex } from "markup-refine-lib/docs/search";

const result = await buildSearchIndex({
  rootDir: generatedSiteDirectory,
  baseUrl: deploymentBase,
});

console.log(result.entries.length, result.outputFile);

Metadata-first, HTML-fallback indexing

The builder resolves each HTML file in this order:

1. Use a versioned data-mr-docs-search-record emitted by DocsPage when present.
2. Use explicit searchContent from that record when provided.
3. Otherwise extract text from main[data-mr-docs-content].
4. For ordinary HTML, fall back to the first main, then body.
5. For the title, fall back through h1, title, then h2.

Plain HTML is supported

A page does not need to use DocsPage. Any generated .html file underrootDir participates in the fallback path.

<!doctype html>
<html lang="en">
  <head>
    <title>Manual installation</title>
  </head>
  <body>
    <main>
      <h1>Manual installation</h1>
      <p>This page is plain generated HTML and is still searchable.</p>
    </main>
  </body>
</html>

Override searchable content when needed

Normally the rendered docs content is the right search text. For generated or unusually noisy pages, DocsPage.searchContent can provide a deliberately concise search corpus while the visible page remains unchanged.

---
import { DocsPage } from "markup-refine-lib/docs";
import { docs } from "../docs.config";
---

<DocsPage
  config={docs}
  title="API generated reference"
  searchContent="API reference clients requests responses authentication"
>
  <GeneratedReference />
</DocsPage>

Generated index format

The output is a JSON array consumed by Markup Refine's static search behavior.

[
  {
    "id": 1,
    "title": "Installation",
    "content": "Install the project ...",
    "url": "/installation/"
  }
]

URL behavior

• Astro integration mode uses Astro's resolved base for derived URLs.
• Generic builder mode uses the supplied baseUrl.
• A structured record can supply its own URL.
• Absolute, protocol-relative, query, and fragment URLs are preserved rather than rebased.

Production search trigger

DocsLayout renders the Markup Refine search trigger in production whenconfig.search is not false. Its default URL is the generatedsearch-index.json under Astro's configured base path. If you intentionally move the integration output to a custom filename, wire the search UI accordingly or keep the default path.