Documentation framework

markup-refine-lib/docs is an optional Astro documentation feature shipped in the same npm package as Markup Refine. It composes the public application shell, clickable list, copyable snippet, card, and search behaviors instead of maintaining a second visual system.

1. Configure navigation once

Navigation is a recursive array of pairs. A string target is a link; another array is a nested sidebar group. Internal links are resolved against Astro's configured base path.

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

export const docs = defineDocs({
  siteName: "My project",
  navigation: [
    ["Overview", "/"],
    [
      "Guide",
      [
        ["Installation", "/installation/"],
        ["Configuration", "/configuration/"],
      ],
    ],
  ],
});

2. Create Astro files per page

The normal page API is intentionally small: import the shared config, provide a title, and write the page body. DocsPage supplies the Markup Refine shell, sidebar, page container, behaviors, and structured search metadata.

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

<DocsPage config={docs} title="Installation">
  <p>Install the project.</p>
</DocsPage>

3. Generate search automatically

The optional Astro integration runs after a static build and writes search-index.jsoninto Astro's resolved output directory. It receives the real output directory and base path from Astro, so the feature does not assume dist/, docs/, or a deployment root.

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

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

Search works with plain HTML too

Pages rendered with DocsPage emit a small versioned JSON search record. The builder uses that metadata first, then extracts searchable text from the rendered docs content. Ordinary HTML files without that record are still indexed by falling back to <main>, then<body>, with title fallback from <h1>, <title>, or<h2>.

The generic builder is available without Astro:

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

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

Used by this documentation site

Markup Refine's ordinary reference and guide pages use DocsPage directly with the shared docsConfig. Standalone demos and website archetypes intentionally remain outside the documentation shell so they can demonstrate full-page markup without interference.

Detailed guides

Documentation API covers navigation, DocsPage, helper components, and source-backed snippets.
Search indexing covers the Astro integration, generic HTML builder, metadata, and fallback extraction.

Dependency boundary

Astro is an optional peer dependency. Importing Markup Refine CSS, behaviors, Layers, or tooltips does not require Astro. The docs components are exposed only from the /docs subpath, while the build integration and generic search builder have their own subpaths.

Current routing limitation

The docs feature currently assumes normal full-page Astro navigation. AstroClientRouter is intentionally unsupported until behavior initialization is made lifecycle-aware and idempotent.

MarkupRefineLib

Menu