# iculizhi/academicpages-stu- architecture

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

- Interactive diagram: https://gitdiagram.com/iculizhi/academicpages-stu-
- Repository: https://github.com/iculizhi/academicpages-stu-

## Overview

##### Project Type and Purpose
- This is a static site generator project built on Jekyll (Ruby), styled with Sass and deployed to GitHub Pages.
- It serves as a personal academic site (blog, publications, talks, notes, portfolio), with optional dynamic maps and comment widgets injected at build time.

##### File Structure
- Content Sources
- `_posts`, `_pages`, `_blogs`, `_notes`, `_talks`, `_teaching`, `_publications`, `_portfolio`, `_drafts`
- `assets/` (CSS, JS, fonts)
- `images/`, `files/`
- `_data/` (YAML: authors, navigation, UI text, comments data)
- Templating & Layout
- `_layouts/` (page templates)
- `_includes/` (Liquid partials for header, footer, comments, analytics, maps, etc.)
- `_sass/` (SCSS modules)
- Configuration & Build
- `_config.yml`, `_config.dev.yml`, `Gemfile` (Ruby deps), `package.json` (JS deps)
- Auxiliary Generators
- `markdown_generator/` (Python + Jupyter notebooks → markdown for publications & talks)
- `talkmap/` (HTML + JS + Leaflet plugin → visitor map)
- Deployment Output
- `_site/` (auto-generated static HTML/CSS/JS—excluded from repo)

##### README Insights
- The author customized academicpages and added DIY instructions.
- Build uses `bundle exec jekyll liveserve`.
- Python scripts preprocess bibliographic and talk data into markdown collections.
- External services (analytics, comments, visitor map) are embedded via HTML snippets in `_includes/`.

##### Main Components & Their Relationships
- Content Repositories → Jekyll Engine
- Markdown + YAML content + `_data/` feeds into Liquid templates.
- Jekyll Engine
- Core runner (Ruby/Gems) reads `_config.yml` → processes SASS, Markdown, Liquid → outputs static files.
- Asset Pipeline
- Sass compiler → CSS
- JS (jQuery + plugins) copied to output
- Python Generators (markdown_generator & talkmap scripts)
- Input: TSV/Bib files → Output: markdown under collections → consumed by Jekyll
- Includes & Layouts
- Modular partials (`_includes/analytics.html`, `_includes/comments.html`, `_includes/feature_row/`, etc.) provide reusable UI blocks
- Deployment & Hosting
- GitHub Pages (serving `_site/`)
- Custom domain via GitHub DNS settings
- External Services
- Analytics providers (Google, custom)
- Comment providers (Disqus, Giscus, Staticman)
- Visitor map (MapMyVisitors or Leaflet bundle)

##### Architectural Patterns & Design Principles
- Static website generator (SSG) pattern
- Modular templating (Liquid includes + layouts)
- Content-config-template separation
- Build-time injection of external widgets (no server-side code)
- Data-driven navigation via `_data/navigation.yml`

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Content
    subgraph "Source Content"
        Posts["_posts"]:::data
        Blogs["_blogs"]:::data
        Notes["_notes"]:::data
        Talks["_talks"]:::data
        Teaching["_teaching"]:::data
        Publications["_publications"]:::data
        Portfolio["_portfolio"]:::data
        Drafts["_drafts"]:::data
        Pages["_pages"]:::data
    end

    %% Data Sources
    subgraph "Data Sources"
        Authors["_data/authors.yml"]:::data
        Navigation["_data/navigation.yml"]:::data
        UIText["_data/ui-text.yml"]:::data
        CommentsData["_data/comments"]:::data
    end

    %% Python Generators
    subgraph "Python Generators"
        MarkdownGen["markdown_generator/"]:::process
        TalkmapScript["talkmap.py & talkmap.ipynb"]:::process
        TalkmapDir["talkmap/"]:::process
    end

    %% Templates & Layouts
    subgraph "Templating & Layouts"
        Layouts["_layouts"]:::process
        Includes["_includes"]:::process
    end

    %% Asset Pipeline
    subgraph "Asset Pipeline"
        Sass["_sass"]:::assets
        CSS["assets/css"]:::assets
        JS["assets/js"]:::assets
        Fonts["assets/fonts"]:::assets
    end

    %% Configuration & Build
    subgraph "Configuration & Build"
        ConfigFiles["_config.yml, _config.dev.yml, Gemfile, package.json"]:::build
        JekyllEngine["Jekyll Engine"]:::build
    end

    %% Output & Deployment
    subgraph "Output & Hosting"
        Output["_site"]:::deploy
        Hosting["GitHub Pages"]:::deploy
    end

    %% External Services
    subgraph "External Services"
        Analytics["Analytics Providers"]:::ext
        CommentsSvc["Comments Providers"]:::ext
        VisitorMap["Visitor Map"]:::ext
    end

    %% Interactions
    Posts --> MarkdownGen
    Blogs --> MarkdownGen
    Notes --> MarkdownGen
    Talks --> MarkdownGen
    Teaching --> MarkdownGen
    Publications --> MarkdownGen
    Portfolio --> MarkdownGen
    Drafts --> MarkdownGen
    Pages --> JekyllEngine

    Authors --> JekyllEngine
    Navigation --> JekyllEngine
    UIText --> JekyllEngine
    CommentsData --> JekyllEngine

    MarkdownGen --> JekyllEngine
    TalkmapScript --> TalkmapDir
    TalkmapDir --> JekyllEngine

    Layouts --> JekyllEngine
    Includes --> JekyllEngine

    Sass --> JekyllEngine
    CSS --> JekyllEngine
    JS --> JekyllEngine
    Fonts --> JekyllEngine

    ConfigFiles --> JekyllEngine
    JekyllEngine --> Output

    Output --> Hosting

    Includes --> Analytics
    Includes --> CommentsSvc
    Includes --> VisitorMap

    %% Click Events
    click Posts "https://github.com/iculizhi/academicpages-stu-/tree/main/_posts/"
    click Blogs "https://github.com/iculizhi/academicpages-stu-/tree/main/_blogs/"
    click Notes "https://github.com/iculizhi/academicpages-stu-/tree/main/_notes/"
    click Talks "https://github.com/iculizhi/academicpages-stu-/tree/main/_talks/"
    click Teaching "https://github.com/iculizhi/academicpages-stu-/tree/main/_teaching/"
    click Publications "https://github.com/iculizhi/academicpages-stu-/tree/main/_publications/"
    click Portfolio "https://github.com/iculizhi/academicpages-stu-/tree/main/_portfolio/"
    click Drafts "https://github.com/iculizhi/academicpages-stu-/tree/main/_drafts/"
    click Pages "https://github.com/iculizhi/academicpages-stu-/tree/main/_pages/"
    click Authors "https://github.com/iculizhi/academicpages-stu-/blob/main/_data/authors.yml"
    click Navigation "https://github.com/iculizhi/academicpages-stu-/blob/main/_data/navigation.yml"
    click UIText "https://github.com/iculizhi/academicpages-stu-/blob/main/_data/ui-text.yml"
    click CommentsData "https://github.com/iculizhi/academicpages-stu-/tree/main/_data/comments/"
    click MarkdownGen "https://github.com/iculizhi/academicpages-stu-/tree/main/markdown_generator/"
    click TalkmapScript "https://github.com/iculizhi/academicpages-stu-/blob/main/talkmap.py"
    click TalkmapDir "https://github.com/iculizhi/academicpages-stu-/tree/main/talkmap/"
    click Layouts "https://github.com/iculizhi/academicpages-stu-/tree/main/_layouts/"
    click Includes "https://github.com/iculizhi/academicpages-stu-/tree/main/_includes/"
    click Sass "https://github.com/iculizhi/academicpages-stu-/tree/main/_sass/"
    click ConfigFiles "https://github.com/iculizhi/academicpages-stu-/blob/main/_config.yml"
    click ConfigFiles "https://github.com/iculizhi/academicpages-stu-/blob/main/_config.dev.yml"
    click ConfigFiles "https://github.com/iculizhi/academicpages-stu-/tree/main/Gemfile"
    click ConfigFiles "https://github.com/iculizhi/academicpages-stu-/blob/main/package.json"
    click CSS "https://github.com/iculizhi/academicpages-stu-/tree/main/assets/css/"
    click JS "https://github.com/iculizhi/academicpages-stu-/tree/main/assets/js/"
    click Fonts "https://github.com/iculizhi/academicpages-stu-/tree/main/assets/fonts/"
    click Output "https://github.com/iculizhi/academicpages-stu-/tree/main/_site/"

    %% Styles
    classDef data fill:#ccffcc,stroke:#2d572c,color:#000;
    classDef process fill:#cce5ff,stroke:#2e5d99,color:#000;
    classDef build fill:#cce0ff,stroke:#3366ff,color:#000;
    classDef assets fill:#ffe5cc,stroke:#cc6600,color:#000;
    classDef deploy fill:#e6e6e6,stroke:#999999,color:#000;
    classDef ext fill:#f2f2f2,stroke:#666666,color:#000;
```
