OpenPress

@open-press/core/mdx

MDX 來源

MDX 來源註冊會作為一個 prop 傳遞給 <Press>。引擎讀取來源以發現內容檔案、編譯區塊，並將它們送入 MdxArea 插槽 — 進而提供給文稿輔助工具、搜尋/替換以及註解標記寫入器使用。

mdxSource 介面提供對外註冊 MDX 內容目錄的功能。系統透過此註冊表收集解析目標，並將編譯後之區塊資料分配給 MdxArea、搜尋引擎及編輯端點。

1.0 契約： 來源聲明為 <Press sources={...}> 的必填屬性。參見 <Press> 元件參考。

Config Impl

# <Press sources>

於 `<Press>` 宣告多個內容資料流，賦予各資料流全域唯一 `id`，供其他文件元件消費或定址。

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

範例：多資料來源註冊

<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

工廠函數，回傳標準化之資料來源註冊物件供 `<Press>` 內部處理。

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

選項 (MdxSourceOptions)

Name Type Default Description
id required string 識別碼。被 ``、`` 及搜尋/替換 CLI 依賴。
preset required "section-folders" | "file-list" `section-folders` 採用慣例目錄結構掃描；`file-list` 則依賴顯式提供的 `files` 清單掃描。
root string 相對於 `press/` 的搜尋根目錄 (如 `report/chapters`)。使用 `file-list` 模式時忽略。
files string[] 指定 `preset: "file-list"` 時的具體 MDX 檔案相對路徑陣列。

範例：慣例目錄解析 (section-folders)

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

系統會將 01-intro/content/ 內的檔案依照字典序拼接合併為單一章節區塊流。

範例：顯式檔案清單 (file-list)

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

內容編譯限制 (Block-only Rule)

來源 MDX 必須嚴格遵循 僅限區塊 (Block-only) 規則。由於渲染器需執行精確的區塊測量與分頁，MDX 內之 JSX 標籤必須為頂層區塊元素，嚴禁出現行內 (inline) 混合 JSX 宣告。

支援之寫法

<TableCaption>Daily ridership</TableCaption>

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

拒絕之寫法 (將拋出編譯錯誤)

這是一段包含 <Highlight>行內標籤</Highlight> 的文字。

依賴與系統整合

來源註冊直接解鎖下列系統功能：

  • 動態渲染：<MdxArea> 利用 chainId 與此來源對接。
  • 自動分頁：<Sections> 與 <Toc> 依靠來源的目錄層級遍歷執行任務。
  • 全域操作：CLI search 與 replace 僅作用於經 mdxSource 註冊的檔案集合。
  • 標記系統：Workbench 的 source-edit 端點與 @openpress-comment 標記寫入器依據來源映射表鎖定檔案修改位置。

資源目錄如元件 (components/)、媒體 (media/) 與主題 (theme/) 不涉及分頁渲染機制，因此不在 sources 的註冊範圍內，而是由 <Press> 其他屬性或慣例處理。