Remark Structure
Extract search records from your documents.
The remarkStructure plugin extracts the headings and contents of a document as records for search. Records keep the Markdown you wrote. See Stringification for how it's generated.
## Installation
Run the [command](/docs/cli) below.
<Callout>Restart the **server** after it.</Callout>
| Option | Default |
| ------ | ------- |
| `dir` | `docs` |Usage
Remark Structure is a remark plugin. Fumadocs MDX enables it by default and exports the records as structuredData. Pass options with remarkStructureOptions.
In Fumadocs MDX, the records are generated with the page props: content inside a <show> that isn't rendered is left out, and expressions are replaced by their values. Outside Fumadocs MDX, expressions are kept as source text.
Records
Headings, paragraphs, blockquotes, tables and JSX elements are recorded (see types):
- Links are replaced by their text, images are removed.
- A table has a record per row, as a table of its header and that row. The rows share a
tablefield. - JSX elements are replaced by their content, except those that
filterElementkeeps (see Components). - A JSX element is a record when it has no children (see
mdxTypes), or fits on one line. - Content inside a record isn't recorded again.
In Fumadocs MDX, the plugin keeps the elements of components by default, like <Callout> but not <div>. Outside Fumadocs MDX, it keeps File, TypeTable, Callout and Card. Change it with filterElement:
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
remarkStructureOptions: {
filterElement: (node) => node.name === 'Callout' || node.name === 'Banner',
},
},
});Components
In Fumadocs MDX, a kept JSX element is recorded in one of two forms, depending on how you read the records:
page.data.structuredData: components aren't rendered. The element is kept as an HTML tag, which search dialogs render as a component. Withasyncordynamiccollections, read it from the loaded page.await page.data.structuredData(): components are rendered for thesearchtarget, and the element is replaced by its Markdown form. Onlyasyncanddynamiccollections have this function.
When rendering, a component is looked up like in MDX: first in the imports and declarations of the file, then in the MDX components of the page props.
Search reads pages from getPages(), which have no custom props. Import or declare a component in the file if search should render it.
A component defines its text for search with asMarkdown():
import { asMarkdown } from 'fumadocs-core/server';
export function ProductName() {
if (asMarkdown()) return 'Fumadocs';
return <span className="font-semibold">Fumadocs</span>;
}A component without a Markdown form is kept as JSX syntax, like an MDX component that is missing from the page props.
Plugins
Nodes inserted by plugins aren't recorded. A plugin adds the records of its node with data.structuredData:
node.data = {
...node.data,
structuredData: {
// `heading` defaults to the current heading
contents: [{ heading: undefined, content: 'Generated **content**' }],
},
};To change the Markdown of authored content in records only, edit the search namespace with replaceSource().
As a Function
On unified, structure() extracts the records from a string:
import { structure } from 'fumadocs-core/mdx-plugins';
import remarkMath from 'remark-math';
// with the remark plugins your content needs
const data = structure(content, [remarkMath], options);Options
Prop
Type
How is this guide?
