# material-components/material-components-site-generator architecture

> Architecture diagram of the GitHub repository material-components/material-components-site-generator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/material-components/material-components-site-generator
- Repository: https://github.com/material-components/material-components-site-generator

## Overview

##### Main Components
- Input Repositories: These are the external Material Component repos that contain Markdown files with Front Matter metadata.
- Build Engine: This is the core transformation pipeline initiated by the "scripts/build" command. It reads the markdown and its Front Matter configuration, rewrites links, and restructures the content as required.
- Template & Theming System: Under “jekyll-site-src” you have Jekyll configuration files, layouts, _includes, CSS/JS assets, and images. This component takes the processed content and applies the appropriate theme/templates (e.g., “detail” for component pages, “landing” for documentation pages).
- iOS Documentation Templates: In “ios-api-docs-src”, you have a separate set of Mustache templates and assets, which indicates that the generator also supports a specialized documentation format (for iOS API docs).
- Auxiliary Libraries and Helpers: Inside “scripts/lib”, you have various helper modules (such as jekyll-config.js, rewrite-local-links.js, project-paths.js, etc.) that implement key functionalities like dependency checking, link rewriting, configuration processing, and more.
- Testing Suite: The “test” directory includes tests ensuring that the documentation processing (like code-patterns and link rewriting) behaves as expected.

##### Relationships and Interactions
- The generator starts by taking one or more documentation repos as input (each marked by an .mdc-docsite.yml file).
- The build script (scripts/build) orchestrates the transformation, calling various helper libraries to process markdown files, extract metadata (using Front Matter), rewrite local links, and route the content for further processing.
- Post-processing, the content is fed into the Jekyll system (located in the “jekyll-site-src” folder), which uses its CSS, JavaScript, and layout templates to generate the final static HTML pages.
- There’s a specialized flow for iOS API Docs that leverages Mustache templates in the “ios-api-docs-src” folder.
- The output is placed within a “dist/” folder, ready to be served as a static website (locally or in production), with separate build flows for development versus production.

##### Architectural Patterns and Technologies
- Pipeline/Transformation Pattern: The flow goes from raw documentation to transformed content using a pipeline of file parsing, metadata extraction, link rewriting, and theming.
- Static Site Generation: Leveraging Jekyll for templating and site structure.
- Multi-Technology Integration: The project integrates Ruby (for gems, bundler), Node.js (for JavaScript libraries and build tools), and standard web technologies (HTML, CSS, JS) in a unified build process.
- Configuration-Driven Processing: Markdown files embed Front Matter metadata which directs how each file should be processed by the generator.
- Environment-Specific Builds: There are clear distinctions between development builds (with source maps and tidied HTML) and production builds (optimized code).

##### Detail and Clarity
- Provide brief descriptions inside or alongside each component denoting its role (for example: “scripts/lib/rewrite-local-links.js: Rewrites links in markdown files to reflect the regenerated site structure”).
- Essential architectural elements—source input, transformation pipeline, templating, and output generation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Input Layer"
        I["Material Component Repositories\n(Markdown Files with Front Matter)"]:::input
    end

    subgraph "Processing Layer"
        BS["Build Script (scripts/build)"]:::process
        BH["Build Helpers (scripts/lib)"]:::process
        BS -->|"calls"| BH
    end

    subgraph "Templating Layer"
        TS["Jekyll Templating (jekyll-site-src)"]:::template
    end

    subgraph "iOS Documentation Flow"
        IOS["iOS API Docs (ios-api-docs-src)"]:::special
    end

    subgraph "Output Layer"
        O["Static Site Output (dist/)"]:::output
    end

    subgraph "Quality Assurance"
        T["Testing Suite (test)"]:::test
    end

    I -->|"processMarkdown"| BS
    BS -->|"transformContent"| TS
    BS -->|"applyMustache"| IOS
    TS -->|"generateHTML"| O
    IOS -->|"generateHTML"| O
    BS -->|"verify"| T

    click BS "https://github.com/material-components/material-components-site-generator/tree/master/scripts/build"
    click BH "https://github.com/material-components/material-components-site-generator/tree/master/scripts/lib"
    click TS "https://github.com/material-components/material-components-site-generator/tree/master/jekyll-site-src"
    click IOS "https://github.com/material-components/material-components-site-generator/tree/master/ios-api-docs-src"
    click T "https://github.com/material-components/material-components-site-generator/tree/master/test"

    classDef input fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef process fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef template fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef special fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef output fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef test fill:#D2B4DE,stroke:#7D3C98,stroke-width:2px;
```
