# marp-team/marpit architecture

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

- Interactive diagram: https://gitdiagram.com/marp-team/marpit
- Repository: https://github.com/marp-team/marpit

## Overview

##### Project Type and Purpose
- Marpit is an open-source JavaScript framework (library) for converting Markdown plus CSS themes into static HTML/CSS slide decks.
- It provides a pipeline of Markdown parsing extensions, CSS‐theming transformations, and slide generation, designed to be embedded in other tools (e.g., marp-core) or used standalone.

##### File Structure Analysis
- Top-level
- plugin.js, index.d.ts, src/index.js: entry points exporting the Marpit API and plugin interface
- src/marpit.js: core engine
- babel.config.js, package.json: build and packaging
- docsify/: scripts and styles for docs site
- test/, jest.config.js: unit tests covering modules
- .circleci/, .github/: CI/CD workflows
- src/
- src/markdown/: extensions to markdown-it (parsers, directives, images, containers, slides, fragments, inline SVG)
- src/helpers/: utility functions used across modules
- src/postcss/: PostCSS plugins handling theme CSS transformations (import, nesting, pseudo-selectors, root rules)
- src/theme.js & src/theme/: base CSS theming system
- docs/ & docsify/: documentation assets and site generator

##### README Insights
- Describes Marpit Markdown extensions, theme-CSS system, inline-SVG support.
- Emphasizes minimal output assets and integration into other converters.
- Points to API docs and guides.

##### Main Components
a. Inputs
- Markdown document + optional CSS theme(s)
- Configuration/options (e.g., enable SVG slides, directives)
b. Marpit Engine
1. Markdown-It Parser with Marpit Plugins
– Directive parser
– Slide background parser
– Fragment, container, image, inline SVG, style parsers
2. Slide Model Builder
– Token splitter, slide container & fragment collectors
– AST augmentation for slides
3. Theme CSS Transformer (PostCSS pipeline)
– import hoisting & replacement
– nesting, pseudo-selector, root rule adjustments
– advanced background, pagination, scaffold, section sizing
4. Renderer
– Convert model + transformed CSS → static HTML + CSS per slide
c. Output
- Static HTML and CSS assets (slide deck)
- Optionally packaged plugin for marp-core or other consumers
d. Tooling & Infrastructure
- Build (Babel) → package.json
- Testing (Jest)
- CI/CD (CircleCI, GitHub Actions)
- Documentation (Docsify)

##### Component Interactions and Data Flow
- Helper modules are invoked throughout parsing & transformation stages.
- External service: npm registry (for publishing), GitHub/GitHub Actions for CI, Codecov.

##### Architectural Patterns and Principles
- Modular pipeline: clear separation of parsing, transformation, rendering.
- Plugin-based extensibility: each Markdown or CSS feature is encapsulated as a plugin.
- Single responsibility per module (e.g., each src/markdown/* directory handles one syntax).
- Testing isolation: mirrored test tree verifying each plugin.

## Diagram (Mermaid)

```mermaid
graph TB
  %% Inputs
  subgraph "Inputs"
    MD["Markdown Document"]:::blue
    CSS["CSS Theme(s)"]:::blue
  end

  %% Plugin API / Entry Points
  Entry["Plugin API & Entry Points"]:::orange

  %% Marpit Engine
  subgraph "Marpit Engine"
    Parser["Markdown-It Parser\nwith Marpit Plugins"]:::green
    ModelBuilder["Slide Model Builder"]:::green
    CSSTransformer["Theme CSS Transformer\n(PostCSS Plugins)"]:::green
    Renderer["Renderer\nHTML/CSS Generator"]:::green
  end

  %% Outputs
  subgraph "Outputs"
    OutputHTML["Static HTML/CSS Assets"]:::blue
    PluginPkg["Plugin for marp-core"]:::blue
  end

  %% Tooling & Infrastructure
  subgraph "Tooling & Infrastructure"
    Build["Build (Babel)"]:::gray
    Test["Testing (Jest)"]:::gray
    CI["CI/CD Workflows"]:::gray
    DocsSite["Documentation (Docsify)"]:::gray
    Docs["Documentation (docs/)"]:::gray
  end

  %% Data Flow
  MD --> Parser
  CSS --> Parser
  Entry --> Parser
  Parser --> ModelBuilder
  ModelBuilder --> CSSTransformer
  CSSTransformer --> Renderer
  Renderer --> OutputHTML
  Renderer --> PluginPkg

  %% Tooling Flow
  Build --> PluginPkg
  Test --> ModelBuilder
  CI --> PluginPkg
  DocsSite --> Docs

  %% Click Events
  click CSS "https://github.com/marp-team/marpit/tree/main/src/theme/"
  click Entry "https://github.com/marp-team/marpit/blob/main/plugin.js"
  click Entry "https://github.com/marp-team/marpit/blob/main/src/plugin.js"
  click Entry "https://github.com/marp-team/marpit/blob/main/src/index.js"
  click Entry "https://github.com/marp-team/marpit/blob/main/index.d.ts"
  click Parser "https://github.com/marp-team/marpit/tree/main/src/markdown/"
  click ModelBuilder "https://github.com/marp-team/marpit/tree/main/src/helpers/"
  click CSSTransformer "https://github.com/marp-team/marpit/tree/main/src/postcss/"
  click Renderer "https://github.com/marp-team/marpit/blob/main/src/index.js"
  click Test "https://github.com/marp-team/marpit/tree/main/test/"
  click CI "https://github.com/marp-team/marpit/blob/main/.circleci/config.yml"
  click DocsSite "https://github.com/marp-team/marpit/tree/main/docsify/"
  click Docs "https://github.com/marp-team/marpit/tree/main/docs/"

  %% Styles
  classDef blue fill:#cce5ff,stroke:#3399ff,color:#003366;
  classDef green fill:#d4edda,stroke:#28a745,color:#155724;
  classDef orange fill:#ffe5b4,stroke:#ff9900,color:#663300;
  classDef gray fill:#e2e3e5,stroke:#6c757d,color:#343a40;
```
