MDX Integration and M3E Atomic Components

TIP
MDX (Markdown + JSX) bridges the gap between static writing and application interfaces. In Shirone, authors can seamlessly mix dynamic logic, reactive Svelte 5 components, and Material 3 design tokens directly within post content.

1. Markdown vs MDX Capability Matrix#

Feature	Standard Markdown (`.md`)	Shirone MDX (`.mdx`)	Execution Mode
Typography & Structure	Full Support	Full Support	Static SSR
Code Highlighting	Line Numbers, Frames, Collapsible	Line Numbers, Frames, Collapsible	Static SSR (Expressive Code)
Diagrams & Mathematics	Mermaid, KaTeX	Mermaid, KaTeX	Client Enhanced
Callout Admonitions	Note, Tip, Important, Warning, Caution	Note, Tip, Important, Warning, Caution	Static SSR
M3E Display Atoms	Not Available	Direct Integration (`<Card>`, `<Skeleton>`)	Pure SSR (Zero Client JS)
Svelte 5 Reactive Islands	Not Available	On-Demand Hydration (`<Button>`, `<Switch>`)	`client:visible` Lazy Hydrated
Feedback & Loading Atoms	Not Available	Animated Morph (`<LoadingIndicator>`)	`client:visible` Reactive
Dynamic JSX Expressions	Not Available	Native Evaluation (`{authorInfo.ui}`)	Compile-Time / Client

2. Dynamic Expressions and Data Mapping#

MDX allows declaring scoped constants using export const at the top of the file, which can be evaluated inline or mapped across templates:

Core Framework: Astro 7
UI Engine: Svelte 5
Design Tokens: M3E Design Tokens
Architecture Pattern: Islands Architecture

Arrays and collections can be rendered dynamically into grid layouts:

1Atomic Component Embedding

Directly import and render 60+ M3E atoms and molecules in article content

2Svelte 5 Islands

Selective hydration via client:visible ensures zero unnecessary JavaScript overhead

3JSX Expressions

Native JavaScript variables, data mappings, and conditional rendering

4Extension Pipeline

Unified SSOT compilation for Mermaid, KaTeX, Admonitions, and Expressive Code

3. M3E Display and Layout Primitives (SSR-Only)#

In accordance with Shirone’s component architecture (docs/atomic-structure.md), stateless display components output clean, accessible semantic HTML with no client-side runtime payload.

3.1 Card Containers (`Card.svelte`)#

Filled Card

Default container background with no elevation shadow. Ideal for grouped content blocks.

Elevated Card

Level 1 container elevation with interactive state layering for heightened visual focus.

Outlined Card

A crisp 1px outline boundary providing clean separation on neutral surfaces.

3.2 Accent Bars and Badges (`AccentBar` & `Badge`)#

System Announcement

Combine AccentBar with Badge to build prominent visual callouts

M3E v0.192

3.3 Skeleton Placeholders (`Skeleton.svelte`)#

For previewing layout skeletons or prototyping async states:

4. Feedback and Loading Indicators#

Shirone features full-fidelity Material 3 Expressive motion and feedback atoms:

4.1 Morphing Loading Indicator (`LoadingIndicator.svelte`)#

Implemented with androidx.graphics.shapes polygon morphing, providing smooth spring-interpolated 7-shape animations:

Indeterminate Shape Morph

Contained Circular Variant

Determinate Progress (68%)

4.2 Linear and Indeterminate Progress (`ProgressIndicator.svelte`)#

Pipeline Compilation80%

Continuous Dual-Line Animation

5. Interactive Svelte 5 Islands#

Components declared with client:visible are lazy-hydrated via IntersectionObserver when entering the viewport:

5.1 Button Matrix (`Button.svelte`)#

5.2 Filter Chips and Segmented Buttons (`Chips` & `SegmentedButton`)#

M3E Filter Chips

Segmented Control

Linear Circular Morphing

5.3 Switches, Checkboxes, and Sliders (`Switch`, `Checkbox`, `Slider`)#

Switch with Status Icons

Selection Checkboxes

Hue Spectrum Slider

5.4 Input Controls (`TextField.svelte`)#

Filled Text Field

Outlined Text Field

6. Markdown Extension Compatibility#

Shirone’s SSOT unified plugin pipeline preserves full compatibility with all Markdown extensions:

6.1 GitHub Repository Cards#

saicaca

fuwari

Waiting for api.github.com...

00K

Waiting...

6.2 Mermaid Architecture Diagrams#

flowchart TD
    MDX[MDX Source Entry] --> Compiler["@astrojs/mdx Compiler"]
    Compiler --> Plugins["Remark / Rehype SSOT Pipeline"]
    Plugins --> Islands["Svelte 5 Interactive Islands"]
    Islands --> Swup["Swup Client Navigation Shell"]
    Swup --> Screen["M3E Expressive Article View"]

6.3 Mathematical Expressions (LaTeX / KaTeX)#

Inline equation: Mass-energy equivalence $E = mc^2$ and Gaussian integral $\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$ .

Block equation:

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

7. Summary#

The native integration of MDX empowers technical writers to build rich, interactive documentation while preserving Shirone’s ultra-fast static performance. All components adhere to the Material 3 Expressive token design system, ensuring consistency, accessibility, and visual harmony.

Shirone

1. Markdown vs MDX Capability Matrix#

2. Dynamic Expressions and Data Mapping#

3. M3E Display and Layout Primitives (SSR-Only)#

3.1 Card Containers (`Card.svelte`)#

3.2 Accent Bars and Badges (`AccentBar` & `Badge`)#

3.3 Skeleton Placeholders (`Skeleton.svelte`)#

4. Feedback and Loading Indicators#

4.1 Morphing Loading Indicator (`LoadingIndicator.svelte`)#

4.2 Linear and Indeterminate Progress (`ProgressIndicator.svelte`)#

5. Interactive Svelte 5 Islands#

5.1 Button Matrix (`Button.svelte`)#

5.2 Filter Chips and Segmented Buttons (`Chips` & `SegmentedButton`)#

5.3 Switches, Checkboxes, and Sliders (`Switch`, `Checkbox`, `Slider`)#

5.4 Input Controls (`TextField.svelte`)#

6. Markdown Extension Compatibility#

6.1 GitHub Repository Cards#

6.2 Mermaid Architecture Diagrams#

6.3 Mathematical Expressions (LaTeX / KaTeX)#

7. Summary#

Continue reading

Take another route

Shirone

1. Markdown vs MDX Capability Matrix#

2. Dynamic Expressions and Data Mapping#

3. M3E Display and Layout Primitives (SSR-Only)#

3.1 Card Containers (Card.svelte)#

3.2 Accent Bars and Badges (AccentBar & Badge)#

3.3 Skeleton Placeholders (Skeleton.svelte)#

4. Feedback and Loading Indicators#

4.1 Morphing Loading Indicator (LoadingIndicator.svelte)#

4.2 Linear and Indeterminate Progress (ProgressIndicator.svelte)#

5. Interactive Svelte 5 Islands#

5.1 Button Matrix (Button.svelte)#

5.2 Filter Chips and Segmented Buttons (Chips & SegmentedButton)#

5.3 Switches, Checkboxes, and Sliders (Switch, Checkbox, Slider)#

5.4 Input Controls (TextField.svelte)#

6. Markdown Extension Compatibility#

6.1 GitHub Repository Cards#

6.2 Mermaid Architecture Diagrams#

6.3 Mathematical Expressions (LaTeX / KaTeX)#

7. Summary#

Share Article

Related reading

Take another route

3.1 Card Containers (`Card.svelte`)#

3.2 Accent Bars and Badges (`AccentBar` & `Badge`)#

3.3 Skeleton Placeholders (`Skeleton.svelte`)#

4.1 Morphing Loading Indicator (`LoadingIndicator.svelte`)#

4.2 Linear and Indeterminate Progress (`ProgressIndicator.svelte`)#

5.1 Button Matrix (`Button.svelte`)#

5.2 Filter Chips and Segmented Buttons (`Chips` & `SegmentedButton`)#

5.3 Switches, Checkboxes, and Sliders (`Switch`, `Checkbox`, `Slider`)#

5.4 Input Controls (`TextField.svelte`)#