# vectorinstitute/mdbook-github-authors architecture

> Architecture diagram of the GitHub repository vectorinstitute/mdbook-github-authors, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vectorinstitute/mdbook-github-authors
- Repository: https://github.com/vectorinstitute/mdbook-github-authors

## Overview

##### Project type and purpose
- This is an open-source mdBook preprocessor plugin written in Rust.
- Its goal is to scan chapter Markdown, detect `{{#author…}}` or `{{#authors…}}` helpers, fetch GitHub profile data for each username, render a “Contributors” section via a Handlebars template, and inject it into the chapter at build time.

##### File structure
- Top-level:
- `.github/` workflows for lint, test, release, docs-test (CI/CD)
- `Cargo.toml` / `Cargo.lock`, `Makefile`, `.gitignore`, `README.md`, `CHANGELOG.md`, `LICENSE`
- Source:
- `src/bin/main.rs` – CLI entrypoint registering the preprocessor with mdBook
- `src/lib.rs` – core library exposing the preprocessor trait impl
- `src/github_authors.rs` – logic to parse authors, call GitHub API, construct data models
- `src/template/authors.hbs` – Handlebars template for rendering the contributors section
- Test artifacts:
- `test_book/` – sample mdBook used by `test_docs.yml` workflow to validate real-world rendering
- `tests/test_preprocessor.rs` – unit/integration tests against `lib`

##### README for additional insights
- Confirms it’s a cargo-installed binary that plugs into `book.toml` under `[preprocessor.github-authors]`.
- Describes the user-facing templating helpers and notes the plugin always appends a styled “Contributors” block to each chapter.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Host
    user["User\n(runs mdbook build)"]:::user
    mdbook["mdBook Host"]:::external

    %% Core Code Modules
    subgraph "Core Code"
        CLI["mdbook-github-authors CLI"]:::code
        Lib["Rust Library\n(Preprocessor trait)"]:::code
        Fetcher["GitHub Data Fetcher"]:::code
        Template["Handlebars Engine\n+ authors.hbs"]:::code
    end

    %% Configuration & Manifest
    Config["book.toml"]:::config
    Manifest["Cargo.toml & Makefile"]:::config
    Docs["README.md & CHANGELOG.md"]:::docs

    %% External Service
    GitHub["GitHub REST API v3"]:::external

    %% Testing and CI
    subgraph "Test & CI"
        TestBook["test_book/"]:::test
        Tests["tests/test_preprocessor.rs"]:::test
        CI[".github/workflows/"]:::ci
    end

    %% Data Flow
    user -->|"mdbook build"| mdbook
    mdbook -->|"stdin JSON + config"| CLI
    Config -->|loaded| CLI
    CLI -->|"delegate"| Lib
    Lib -->|"parse helpers"| Fetcher
    Fetcher -->|"HTTP GETs"| GitHub
    GitHub -->|"JSON profiles"| Fetcher
    Fetcher -->|"context object"| Lib
    Lib -->|"render with template"| Template
    Template -->|"rendered Markdown"| Lib
    Lib -->|"JSON output"| CLI
    CLI -->|"stdout"| mdbook

    %% Testing & CI Flows
    CI -->|"runs unit tests"| Tests
    CI -->|"runs docs tests"| TestBook
    Tests -->|"validate Lib"| Lib
    TestBook -->|"example build"| mdbook

    %% Manifest & Docs references
    Manifest -->|defines build| CLI
    Docs -->|user guidance| user

    %% Click Events
    click CLI "https://github.com/vectorinstitute/mdbook-github-authors/blob/main/src/bin/main.rs"
    click Lib "https://github.com/vectorinstitute/mdbook-github-authors/blob/main/src/lib.rs"
    click Fetcher "https://github.com/vectorinstitute/mdbook-github-authors/blob/main/src/github_authors.rs"
    click Template "https://github.com/vectorinstitute/mdbook-github-authors/blob/main/src/template/authors.hbs"
    click Config "https://github.com/vectorinstitute/mdbook-github-authors/blob/main/test_book/book.toml"
    click TestBook "https://github.com/vectorinstitute/mdbook-github-authors/tree/main/test_book/"
    click Tests "https://github.com/vectorinstitute/mdbook-github-authors/blob/main/tests/test_preprocessor.rs"
    click CI "https://github.com/vectorinstitute/mdbook-github-authors/tree/main/.github/workflows/"
    click Manifest "https://github.com/vectorinstitute/mdbook-github-authors/blob/main/Cargo.toml"
    click Manifest "https://github.com/vectorinstitute/mdbook-github-authors/tree/main/Makefile"
    click Docs "https://github.com/vectorinstitute/mdbook-github-authors/blob/main/README.md"
    click Docs "https://github.com/vectorinstitute/mdbook-github-authors/blob/main/CHANGELOG.md"

    %% Styles
    classDef code fill:#AED6F1,stroke:#2E86C1,color:#1B4F72;
    classDef external fill:#A9DFBF,stroke:#28B463,color:#1D8348;
    classDef ci fill:#F9E79F,stroke:#B7950B,color:#7D6608;
    classDef config fill:#D5DBDB,stroke:#7B7D7D,color:#424949;
    classDef test fill:#E8DAEF,stroke:#8E44AD,color:#512E5F;
    classDef docs fill:#D5DBDB,stroke:#626567,color:#1B2631;
    classDef user fill:#FADBD8,stroke:#C0392B,color:#641E16;
```
