How marp-team/marpit works
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.