docs: clarify difference between markmap and options

Author: maxchang3

README.md

@@ -55,7 +55,19 @@ All frontmatter options are optional.
 
 - **`id`** : Used to define the ID of the `markmap-wrap` element.  
 
--  **`markmap`**/**`options`** : Correspond to the [`IMarkmapJSONOptions`](https://markmap.js.org/api/interfaces/markmap-view.IMarkmapJSONOptions.html) in the markmap project. For more details, please refer to [`jsonOptions`](https://markmap.js.org/docs/json-options#option-list).
+- **`markmap`** : Correspond to the [`IMarkmapJSONOptions`](https://markmap.js.org/api/interfaces/markmap-view.IMarkmapJSONOptions.html) in the markmap project. For more details, please refer to [`jsonOptions`](https://markmap.js.org/docs/json-options#option-list).
+  - alias: **`options`** (for backward compatibility)
+
+> [!TIP] 
+> **Difference between `markmap` and `options`**
+> 
+> - **`markmap` (from markmap-lib)** 
+>   [Preprocesses](https://github.com/markmap/markmap/blob/master/packages/markmap-lib/src/plugins/frontmatter/index.ts#L41) JSON options (e.g., converting strings to arrays or numbers) and overrides the legacy `options`.
+>   - For example, `color: 'red'` will be converted to `color: ['red']`, only the latter is valid in `markmap-view`.
+>   - ✅ Recommended for consistent use with `markmap`.
+> 
+> - **`options` (from markmap-universe)** Passed directly to markmap-view.  
+>   - ❌ Not recommended, maintained only for backward compatibility.
 
 
 #### Tag Options

README.zh.md

@@ -51,9 +51,22 @@ markmap:
 
 所有 frontmatter 选项都是可选的。
 
-- **`id`** : 用于定义 `markmap-wrap` 元素的 ID。  
+- **`id`**：用于定义 `markmap-wrap` 元素的 ID。  
 
-- **`markmap`**/**`options`** : 对应 markmap 项目中 [`IMarkmapJSONOptions`](https://markmap.js.org/api/interfaces/markmap-view.IMarkmapJSONOptions.html)。有关更多详细信息，请参阅 [`jsonOptions`](https://markmap.js.org/docs/json-options#option-list).
+- **`markmap`**/**`options`**：对应 markmap 项目中的 [`IMarkmapJSONOptions`](https://markmap.js.org/api/interfaces/markmap-view.IMarkmapJSONOptions.html)。有关更多详细信息，请参考 [`jsonOptions`](https://markmap.js.org/docs/json-options#option-list)。
+  - 别名：**`options`**（向后兼容）
+
+> [!TIP]
+> **`markmap` 和 `options` 的区别**
+> 
+> - **`markmap`（来自 markmap-lib）**  
+>  JSON Options 会被[预处理](https://github.com/markmap/markmap/blob/master/packages/markmap-lib/src/plugins/frontmatter/index.ts#L41)（例如，将字符串转换为数组或数字），并优先覆盖 `options`。  
+>   - 例如，`color: 'red'` 会被转换为 `color: ['red']`，只有后者在 `markmap-view` 中有效。  
+>   - ✅ 推荐使用，以保持与 `markmap` 一致。
+> 
+> - **`options`（来自 markmap-universe）** 会被直接传递给 markmap-view。  
+>   - ❌ 不推荐使用，仅为向后兼容而保留。
+>
 
 #### 标签选项