How material-components/material-components-site-generator works
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.