1078 字
5 分钟
MDX 集成与 M3E 原子组件

1. Markdown 与 MDX 能力对照#

能力标准 Markdown(.md)Shirone MDX(.mdx)执行方式
排版与结构完整支持完整支持静态 SSR
代码高亮行号、框架、可折叠行号、框架、可折叠静态 SSR(Expressive Code)
图表与数学Mermaid、KaTeXMermaid、KaTeX客户端增强
提示容器Note、Tip、Important、Warning、CautionNote、Tip、Important、Warning、Caution静态 SSR
M3E 展示原子不可用直接集成(<Card>、<Skeleton>)纯 SSR(零客户端 JS)
Svelte 5 响应式孤岛不可用按需水合(<Button>、<Switch>)client:visible 懒水合
反馈与加载原子不可用形变动画(<LoadingIndicator>)client:visible 响应式
动态 JSX 表达式不可用原生求值({authorInfo.ui})编译期 / 客户端

2. 动态表达式与数据映射#

MDX 允许在文件顶部用 export const 声明作用域常量,可行内求值或跨模板映射:

  • 核心框架:Astro 7
  • UI 引擎:Svelte 5
  • 设计令牌:M3E 设计令牌
  • 架构模式:孤岛架构

数组与集合可动态渲染为网格布局:

1原子组件嵌入

直接在文章内容中引入并渲染 60+ 个 M3E 原子与分子组件

2Svelte 5 孤岛

通过 client:visible 选择性水合,零冗余 JavaScript 开销

3JSX 表达式

原生 JavaScript 变量、数据映射与条件渲染

4扩展管线

Mermaid、KaTeX、提示容器与 Expressive Code 的统一 SSOT 编译


3. M3E 展示与布局基元(仅 SSR)#

依据 Shirone 的组件架构(docs/atomic-structure.md),无状态展示组件输出干净、无障碍的语义化 HTML,不带任何客户端运行时负载。

3.1 卡片容器(Card.svelte)#

填充卡片
默认容器背景,无海拔阴影,适合成组的内容块。
海拔卡片
一级容器海拔,带交互态层叠,视觉更聚焦。
描边卡片
清晰的 1px 描边,在中性表面上提供干净的分隔。

3.2 强调条与徽标(AccentBar 与 Badge)#

系统公告

把 AccentBar 与 Badge 组合,做出醒目的视觉提示

M3E v0.192

3.3 骨架屏占位(Skeleton.svelte)#

用于预览布局骨架或原型化异步状态:


4. 反馈与加载指示器#

Shirone 具备完整的 Material 3 Expressive 动效与反馈原子:

4.1 形变加载指示器(LoadingIndicator.svelte)#

基于 androidx.graphics.shapes 多边形形变,提供平滑弹簧插值的 7 形状动画:

不确定形状形变
内含圆形变体
确定性进度(68%)

4.2 线性与不确定进度(ProgressIndicator.svelte)#

管线编译80%
连续双线动画

5. 交互式 Svelte 5 孤岛#

用 client:visible 声明的组件,会在进入视口时经 IntersectionObserver 懒水合:

5.1 按钮矩阵(Button.svelte)#

5.2 筛选芯片与分段按钮(Chips 与 SegmentedButton)#

M3E 筛选芯片
分段控件

5.3 开关、复选框与滑块(Switch、Checkbox、Slider)#

带状态图标的开关
选择复选框
色相光谱滑块

5.4 输入控件(TextField.svelte)#

填充文本框
描边文本框

6. Markdown 扩展兼容性#

Shirone 的 SSOT 统一插件管线对所有 Markdown 扩展保持完整兼容:

6.1 GitHub 仓库卡片#

saicacafuwari

6.2 Mermaid 架构图#

flowchart TD
    MDX[MDX 源码入口] --> Compiler["@astrojs/mdx 编译器"]
    Compiler --> Plugins["Remark / Rehype SSOT 管线"]
    Plugins --> Islands["Svelte 5 交互孤岛"]
    Islands --> Swup["Swup 客户端导航壳"]
    Swup --> Screen["M3E Expressive 文章视图"]

6.3 数学表达式(LaTeX / KaTeX)#

行内公式:质能方程 E=mc2E = mc^2 与高斯积分 ∫−∞∞e−x2dx=π\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}。

块级公式:

LM3E=∑i=1N(Tokeni⋅ContrastRatio)+λ∥MotionElegance∥\mathcal{L}_{M3E} = \sum_{i=1}^{N} \left( \text{Token}_i \cdot \text{ContrastRatio} \right) + \lambda \|\text{MotionElegance}\|

7. 小结#

MDX 的原生集成让技术写作者在保持 Shirone 超快静态性能的同时,构建出富交互文档。所有组件遵循 Material 3 Expressive 令牌设计体系,确保一致性、无障碍与视觉和谐。

第 19 篇,共 20 篇本文属于系列

分享文章

生成精美分享图或复制链接,与更多人分享本文。

继续阅读

沿着主题读

基于共同的标签与分类

换条路线

从其他文章中稳定抽取