# howard-haowen/slides2pages architecture

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

- Interactive diagram: https://gitdiagram.com/howard-haowen/slides2pages
- Repository: https://github.com/howard-haowen/slides2pages

## Overview

##### Project Type and Purpose
- This is a specialized automation project that leverages Marp (a Markdown-to-slide/PDF conversion tool) for turning markdown presentations into HTML webpages. It is essentially an integration and deployment pipeline tool that uses GitHub Actions to run conversion jobs and then publishes the converted output (HTML/PDF) as a GitHub Pages site.
- The README highlights both manual usage (via npx commands) and automation via a GitHub workflow that calls a Marp CLI Docker container, so the project serves both as a guide/template and a working system for transforming presentation content.

##### File Structure
- Top-level Directories:
- .github/workflows: Contains the CI/CD configuration. The “marp-to-pages.yml” file defines the workflow that runs the Marp conversion command (using a Docker image) to generate build outputs.
- docs: Contains various markdown files which are likely slides or additional documentation that are processed by Marp and deployed.
- package.json: Manages dependencies, including the Marp CLI when installed via npm, indicating that local development and one-off conversions can be performed.
- .marprc.yml and other configuration files provide directives for Marp rendering.
- Other important files include README.md (which doubles as a landing page) and image assets used for documentation.

##### Main Components
a. Repository Content:
- Source Code & Configuration: Markdown files (README.md, docs/…), themes, config files (such as .marprc.yml), and package.json.
- This is the starting point where a developer commits changes.

b. CI/CD Pipeline (GitHub Actions):
- The .github/workflows directory defines jobs that trigger on commits or merges.
- The workflow “marp-to-pages.yml” calls the Docker image (from marpteam/marp-cli) to process markdown files into PDF and HTML formats.

c. Marp Conversion Process:
- The transformation step where Marp CLI (whether via npx locally or deployed in a Docker container) takes a markdown file (e.g., README.md or docs/…) and generates output (PDF/HTML).
- Transformation from Markdown + CSS Themes (from “themes/”) to finished artifacts.

d. Deployment Layer:
- The conversion output is then pushed to a deployment branch (commonly “gh-pages”) which is automatically published via GitHub Pages.
- This component represents the “web hosting” endpoint for the generated slides.

e. External Tools & Services:
- The integration of Docker (as seen in the workflow) and GitHub Pages service should be separately noted.
- Npm as part of local development dependencies.

##### Relationships and Interactions
- If drawing an extended view, also show manual development paths (e.g., local conversions via npx marp command).

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clear separation between source content (Markdown, theme files) and build/deployment processes.
- Automation and Continuous Deployment: The CI/CD pipeline automates the conversion process and pushes output to a website, reflecting modern DevOps principles.
- Containerization: Utilizing Docker to run standardized Marp CLI commands in an isolated environment.
- Modularity: Provides options for on-demand transformation (both via local CLI and GitHub Actions).

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Source Repository"
        R1["README.md"]:::file
        R2["package.json"]:::file
        R3[".marprc.yml"]:::file
        R4["Docs"]:::folder
        R5["Themes"]:::folder
    end

    subgraph "Manual/Local Process"
        LC["Local Conversion (npx marp)"]:::process
    end

    CI["CI/CD Pipeline (GitHub Actions)"]:::ci
    DC["Docker Container (Marp CLI)"]:::process
    BA["Build Artifacts (PDF/HTML)"]:::artifact
    GP["GitHub Pages (Deployment)"]:::deploy

    R4 --> CI
    R4 --> LC
    R5 --> DC
    CI --> DC
    DC --> BA
    LC --> BA
    BA --> GP

    click R1 "https://github.com/howard-haowen/slides2pages/blob/main/README.md"
    click R2 "https://github.com/howard-haowen/slides2pages/blob/main/package.json"
    click R3 "https://github.com/howard-haowen/slides2pages/blob/main/.marprc.yml"
    click R4 "https://github.com/howard-haowen/slides2pages/tree/main/docs/"
    click R5 "https://github.com/howard-haowen/slides2pages/tree/main/themes/"
    click CI "https://github.com/howard-haowen/slides2pages/blob/main/.github/workflows/marp-to-pages.yml"

    classDef file fill:#fef3bd,stroke:#b58900,stroke-width:2px;
    classDef folder fill:#e0f7fa,stroke:#006064,stroke-width:2px;
    classDef ci fill:#dcedc1,stroke:#33691e,stroke-width:2px;
    classDef process fill:#ffccbc,stroke:#bf360c,stroke-width:2px;
    classDef artifact fill:#d1c4e9,stroke:#311b92,stroke-width:2px;
    classDef deploy fill:#c8e6c9,stroke:#1b5e20,stroke-width:2px;
```
