# nuxt-modules/mdc architecture

> Architecture diagram of the GitHub repository nuxt-modules/mdc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nuxt-modules/mdc
- Repository: https://github.com/nuxt-modules/mdc

## Overview

##### Project Type and Purpose
- This is a Nuxt/Vue module (“@nuxtjs/mdc”) that extends Markdown by deeply integrating Vue components (MDC = “MarkDown Components”).
- It provides two core runtime capabilities: parsing raw Markdown into an intermediate AST, and rendering that AST into interactive Vue components in the browser (or server).

##### High-Level Architectural Macro–Areas
A. Runtime Parsing (blue)
B. Runtime Rendering (green)

##### Main Components & Flow
1. Input (Raw Markdown)
- Sources: `.md` files, inline strings in Vue components, or Playground endpoint (`playground/server/api/markdown.ts`).
2. Runtime Parsing (blue zone)
- parseMarkdown() entry point (src/runtime/index.ts)
- Parser pipeline:
- Remark-based tokenizer (src/runtime/parser)
- rehype transformer (src/runtime/highlighter/rehype.ts)
- Optional syntax highlighter plugin (Shiki via rehype-nuxt.ts / shiki.ts)
- AST utilities (src/runtime/utils/ast.ts, etc.)
- Output: MDCParserResult (AST body + metadata)
3. Runtime Rendering (green zone)
- MDC.vue wrapper → MDCRenderer.vue (src/runtime/components)
- MDCRenderer takes AST → recursively renders nodes:
- Prose components map (ProseP, ProseH1… in src/runtime/components/prose)
- Block components (Alert, Callout etc. under `components/mdc`)
- MDCSlot for unwrapping wrappers
- Async component resolution (AsyncComponent.vue, PageSnippet.vue in playground)
- Final output: Vue VNodes → DOM
4. Feedback & Extensions
- Config module (src/module.ts) for Nuxt integration, global component registration, user overrides
- Playground environment demonstrates end-to-end flow

##### Relationships and Interactions
- Side note: Nuxt module config injects runtime parsing/rendering into Nuxt build

##### Architectural Patterns & Principles
- Clear separation of Concerns: parsing pipeline vs. rendering pipeline
- Plugin architecture: remark and rehype plugins can be extended
- Component map injection: map HTML tags → Vue components (prose map)
- Asynchronous rendering flow using Vue Suspense

##### Final Touches
- Every component and sub-module is clearly named.
- Keep it simple: only two macro areas with their internal sub-components listed.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Runtime Parsing Zone
    subgraph "Runtime Parsing" 
        direction TB
        InputMarkdown["📄 Raw Markdown"]:::parsing
        ParseMD["parseMarkdown()"]:::parsing
        Tokenizer["Remark Tokenizer"]:::parsing
        Rehype["rehype Transformer"]:::parsing
        Highlighter["Shiki Plugin"]:::parsing
        ASTUtils["AST Utilities"]:::parsing
        ASTOutput["MDCParserResult (AST)"]:::parsing
    end

    %% Runtime Rendering Zone
    subgraph "Runtime Rendering"
        direction TB
        MDCWrapper["MDC.vue Wrapper"]:::rendering
        Renderer["MDCRenderer.vue"]:::rendering
        ProseMap["Prose Components Map"]:::rendering
        Slot["MDCSlot"]:::rendering
        AsyncComp["Async Components"]:::rendering
        DOMOutput["🖥️ Vue VNodes → DOM"]:::rendering
    end

    %% Flow Arrows
    InputMarkdown -->|"raw markdown"| ParseMD
    ParseMD -->|"token stream"| Tokenizer
    Tokenizer -->|"hast"| Rehype
    Rehype -->|"with highlights"| Highlighter
    Highlighter -->|"AST enhancements"| ASTUtils
    ASTUtils -->|"AST body + metadata"| ASTOutput

    ASTOutput -->|"AST body + metadata"| MDCWrapper
    MDCWrapper -->|"AST prop"| Renderer
    Renderer -->|"renders nodes"| ProseMap
    Renderer -->|"renders wrappers"| Slot
    Renderer -->|"suspense"| AsyncComp
    Renderer -->|"vnode tree"| DOMOutput

    %% Click Events
    click ParseMD "https://github.com/nuxt-modules/mdc/blob/main/src/runtime/index.ts"
    click Tokenizer "https://github.com/nuxt-modules/mdc/blob/main/src/runtime/parser/index.ts"
    click Tokenizer "https://github.com/nuxt-modules/mdc/tree/main/src/runtime/parser/"
    click Rehype "https://github.com/nuxt-modules/mdc/blob/main/src/runtime/highlighter/rehype.ts"
    click Highlighter "https://github.com/nuxt-modules/mdc/blob/main/src/runtime/highlighter/shiki.ts"
    click Highlighter "https://github.com/nuxt-modules/mdc/blob/main/src/runtime/highlighter/rehype-nuxt.ts"
    click ASTUtils "https://github.com/nuxt-modules/mdc/blob/main/src/runtime/utils/ast.ts"
    click ASTUtils "https://github.com/nuxt-modules/mdc/tree/main/src/runtime/utils/"
    click ASTOutput "https://github.com/nuxt-modules/mdc/blob/main/src/types/parser.ts"
    click MDCWrapper "https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/MDC.vue"
    click Renderer "https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/MDCRenderer.vue"
    click Slot "https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/MDCSlot.vue"
    click ProseMap "https://github.com/nuxt-modules/mdc/tree/main/src/runtime/components/prose/"
    click AsyncComp "https://github.com/nuxt-modules/mdc/blob/main/playground/components/global/AsyncComponent.vue"
    click AsyncComp "https://github.com/nuxt-modules/mdc/blob/main/playground/components/global/PageSnippet.vue"
    click DOMOutput "https://github.com/nuxt-modules/mdc/tree/main/playground/components/mdc/"
    click InputMarkdown "https://github.com/nuxt-modules/mdc/blob/main/playground/server/api/markdown.ts"

    %% Styles
    classDef parsing fill:#e0f3ff,stroke:#1f78b4,stroke-width:1px
    classDef rendering fill:#e0ffe0,stroke:#33a02c,stroke-width:1px
    class InputMarkdown,ParseMD,Tokenizer,Rehype,Highlighter,ASTUtils,ASTOutput parsing
    class MDCWrapper,Renderer,ProseMap,Slot,AsyncComp,DOMOutput rendering
```
