OpenPress

@open-press/core/mdx

MDX Sources

MDX source registrations are passed as a prop to <Press>. The engine reads sources to discover content files, compile blocks, and flow them into MdxArea slots — making them available for manuscript utilities, search/replace, and the comment marker writer.

The mdxSource interface provides the functionality to externally register MDX content directories. The system collects parse targets via this registry and allocates compiled block data to MdxArea, the search engine, and editing endpoints.

1.0 Contract: Source declaration is a required prop for <Press sources={...}>. See the <Press> component reference.

Config Impl

# <Press sources>

Declares multiple content data streams in `<Press>`, assigning each a globally unique `id` for consumption or addressing by other document components.

<Press sources={[
  mdxSource({ id: "story", preset: "section-folders", root: "chapters" }),
]}>

Example: Multiple Data Source Registration

<Press
  title="Paper"
  page="a4"
  sources={[
    mdxSource({ id: "story", preset: "section-folders", root: "report/chapters" }),
    mdxSource({ id: "appendix", preset: "section-folders", root: "report/appendix" }),
  ]}
>
  <Sections source="story" />
  <Sections source="appendix" />
</Press>
Function Impl

# mdxSource

Factory function returning a standardized data source registration object for internal processing by `<Press>`.

import { mdxSource } from "@open-press/core/mdx";
mdxSource(options: MdxSourceOptions): SourceRegistration

Options (MdxSourceOptions)

Name Type Default Description
id required string Identifier. Depended upon by ``, ``, and search/replace CLI.
preset required "section-folders" | "file-list" `section-folders` scans using conventional directory structures; `file-list` scans relying on an explicitly provided `files` list.
root string The search root relative to `press/` (e.g., `report/chapters`). Ignored when using `file-list` mode.
files string[] An array of specific relative MDX file paths when `preset: "file-list"` is specified.

Example: Conventional Directory Resolution (section-folders)

press/
  report/
    chapters/
      01-intro/
        content/
          01-overview.mdx
          02-context.mdx

The system will concatenate and merge files within 01-intro/content/ in lexicographical order into a single chapter block stream.

Example: Explicit File List (file-list)

mdxSource({
  id: "story",
  preset: "file-list",
  files: ["intro.mdx", "results.mdx", "conclusion.mdx"],
});

Content Compilation Restrictions (Block-only Rule)

Source MDX must strictly follow the Block-only rule. Because the renderer needs to perform precise block measurement and pagination, JSX tags within MDX must be top-level block elements; inline mixed JSX declarations are strictly forbidden.

Supported Syntax

<TableCaption>Daily ridership</TableCaption>

| Day | Riders |
| --- | --- |
| Mon | 1,204 |

Rejected Syntax (Will throw a compilation error)

This is a piece of text containing <Highlight>inline tags</Highlight>.

Dependencies and System Integration

Source registration directly unlocks the following system features:

  • Dynamic Rendering: <MdxArea> interfaces with this source using chainId.
  • Auto-pagination: <Sections> and <Toc> rely on the source’s directory tree traversal to execute tasks.
  • Global Operations: CLI search and replace only operate on file sets registered via mdxSource.
  • Markup System: The Workbench’s source-edit endpoint and @openpress-comment marker writer target file modification locations based on the source map.

Resource directories such as components (components/), media (media/), and theme (theme/) do not involve the pagination rendering mechanism, and are therefore not within the registration scope of sources, but are handled by other <Press> properties or conventions.