Documentation API

Build an Astro documentation site by configuring navigation once and wrapping each page with DocsPage.

The markup-refine-lib/docs subpath is the high-level documentation abstraction for Markup Refine. It owns the application shell, nested sidebar, sidebar filtering and persistence, active-page selection, page container, copy behavior, and search metadata. A consumer normally supplies one shared configuration object and creates Astro pages.

Intended workflow

Configure navigation once, create one Astro file per route, and render the page throughDocsPage. You do not need to reproduce Markup Refine shell/sidebar markup yourself.

Configure the site once

defineDocs() preserves the literal navigation tuple types while validating the shared documentation configuration. A navigation item is either [name, href] or[name, children], and groups can be nested recursively.

docs.config.ts

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

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

defineDocs() configuration
Name	Type	Required	Default	Description
`siteName`	`string`	Yes	—	Name rendered in the documentation shell and used to namespace persisted navigation state.
`navigation`	`DocsNavigation`	Yes	—	Recursive [name, href] and [name, children] tuples used to build the sidebar.
`description`	`string`	No	—	Default document meta description when a page does not provide its own description.
`lang`	`string`	No	`"en"`	Value used for the generated html lang attribute.
`search`	`boolean`	No	`true`	Controls the production search trigger. Set false when the site does not generate a search index.

Create pages with DocsPage

Each documentation route imports the shared configuration and uses DocsPage. Internal navigation links beginning with / are resolved against Astro's configured base path; fragment, query, protocol-relative, and absolute URLs are left unchanged.

src/pages/installation.astro

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

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

DocsPage props
Name	Type	Required	Description
`config`	`DocsConfig`	Yes	Shared configuration returned by defineDocs().
`title`	`string`	Yes	Page heading and document-title prefix.
`description`	`string`	No	Page-specific description rendered below the heading and used as the meta description.
`searchContent`	`string`	No	Optional explicit search text. When omitted, the index builder extracts rendered page content.
`titleId`	`string`	No	Optional id applied to the generated page h1 for stable fragment links.

Navigation behavior

The sidebar generated from the tuple tree automatically composes Markup Refine primitives:

nested groups are rendered as disclosure sections;
group disclosure state uses stable generated IDs and is persisted per site name;
the current page is selected by the clickable-list behavior;
the sidebar filter is provided by the same clickable-list behavior;
the application shell provides the responsive sidebar/drawer behavior.

Optional documentation components

DocsPage is the only component needed for the basic site structure. The same public entry also exposes small helpers for common reference-documentation content.

import {
  ApiTable,
  Callout,
  CodeBlock,
  DocsPage,
  Example,
  readCodeSnippet,
} from "markup-refine-lib/docs";

CodeBlock renders an optionally copyable source block.
Callout maps semantic variants to Markup Refine card variants.
Example pairs a rendered example card with optional source.
ApiTable renders compact API-reference tables.
readCodeSnippet() reads real source files at build time for source-backed examples.
DocsLayout and DocsSidebar remain available as lower-level escape hatches.

Source-backed snippets

readCodeSnippet() accepts a path or file URL supplied by the project. Selection can be by line range or marker range, but the two modes cannot be mixed.

const source = await readCodeSnippet({
  source: new URL("../example.ts", import.meta.url),
  startMarker: "docs:start",
  endMarker: "docs:end",
});

Search is optional

Search is enabled in production by default. If a project does not install the docs integration or otherwise generate search-index.json, disable the trigger in the shared configuration.

export const docs = defineDocs({
  siteName: "My project",
  search: false,
  navigation: [
    ["Overview", "/"],
  ],
});

See Search indexing for automatic Astro builds, plain HTML indexing, custom output locations, and the generated index format.

Astro compatibility

ClientRouter is not supported yet

The current docs feature assumes normal full-page Astro navigation. Do not add AstroClientRouter until Markup Refine behavior initialization is lifecycle-aware and idempotent.

MarkupRefineLib

Menu