# hyperzsb/natalia-theme architecture

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

- Interactive diagram: https://gitdiagram.com/hyperzsb/natalia-theme
- Repository: https://github.com/hyperzsb/natalia-theme

## Overview

##### Project type and purpose
- “natalia-theme” is an **open-source Jekyll & Bootstrap theme** for building a static portfolio + blog.
- It provides layouts, includes, styles, scripts, and configuration so that a user can drop in their content (Markdown posts, project pages, personal data in `_config.yaml`) and generate a fully functional static site.

##### File structure
- Top-level directories:
- `_layouts`: HTML templates (default, post, project)
- `_includes`: reusable fragments (header, footer, TOC, loading, anchor headings)
- `_pages`: standalone pages (home, posts listing, projects listing, contact, 404)
- `_posts` & `_projects`: Markdown content for blog posts and project details
- `_sass`: SCSS partials for theming
- `assets`: compiled CSS (via SCSS), JavaScript (dark mode toggle, email form logic, Gitalk init, utils), images
- Configuration files:
- `Gemfile` / `Gemfile.lock`: Ruby gem dependencies (Jekyll core + plugins)
- `_config.yaml`: site metadata, plugin settings (Gitalk, EmailJS, Clarity), deploy settings (`url`, `baseUrl`)
- Build / deploy files:
- GitHub Actions workflow for GitHub Pages deployment (inferred by badge)
- Standard Jekyll build output in `_site/`

##### Key architectural notes from README
- Static-site generation pipeline using **Jekyll** + **Liquid** + **Sass**
- JavaScript enhancements for: comments (Gitalk/Preact), email (EmailJS), syntax highlighting (HighlightJS), math rendering (MathJax), analytics (Microsoft Clarity), dark mode
- Users customize via `_config.yaml`; sensitive values (clientSecret, service IDs) are recommended to be injected via environment variables in CI/hosting

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Environment
    subgraph "Developer Environment" 
        direction TB
        Config["_config.yaml"]:::build
        Gemfile["Gemfile"]:::build
        GemfileLock["Gemfile.lock"]:::build
        subgraph "Layouts" 
            direction TB
            Default["_layouts/default.html"]:::build
            PostLayout["_layouts/post.html"]:::build
            ProjectLayout["_layouts/project.html"]:::build
        end
        subgraph "Includes"
            direction TB
            Header["_includes/header.html"]:::build
            Footer["_includes/footer.html"]:::build
            TOC["_includes/toc.html"]:::build
            Loading["_includes/loading.html"]:::build
            Anchors["_includes/anchor_headings.html"]:::build
        end
        subgraph "Pages"
            direction TB
            Home["_pages/home.html"]:::build
            PostsPage["_pages/posts.html"]:::build
            ProjectsPage["_pages/projects.html"]:::build
            Contact["_pages/contact.html"]:::build
            NotFound["_pages/404.html"]:::build
        end
        subgraph "Content (Markdown)"
            direction TB
            Post1["_posts/2022-03-03-post-1.md"]:::build
            Post2["_posts/2022-03-04-post-2.md"]:::build
            Post3["_posts/2022-03-05-post-3.md"]:::build
            Post4["_posts/2022-03-06-post-4.md"]:::build
            Project1["_projects/project-1.md"]:::build
            Project2["_projects/project-2.md"]:::build
            Project3["_projects/project-3.md"]:::build
            Project4["_projects/project-4.md"]:::build
            Bio["_biographies/biography.md"]:::build
        end
        subgraph "Sass Partials"
            direction TB
            MainSCSS["_sass/main.scss"]:::build
            GitalkSCSS["_sass/gitalk.scss"]:::build
            MarkdownSCSS["_sass/markdown.scss"]:::build
            TocSCSS["_sass/toc.scss"]:::build
        end
        subgraph "JavaScript & Utilities"
            direction TB
            MainJS["assets/js/main.js"]:::client
            DarkMode["assets/js/dark-mode.js"]:::client
            EmailJS["assets/js/email.js"]:::client
            UtilsJS["assets/js/utils.js"]:::client
        end
    end

    DeveloperEnv["Developer"]:::actor

    %% Source Repository
    GitHub["GitHub Repository"]:::infra

    %% CI / Build System
    subgraph "CI / Build System" 
        direction TB
        Bundle["Bundler & Gems"]:::build
        Jekyll["Jekyll Build (Liquid + Markdown)"]:::build
        Sass["Sass Compiler"]:::build
        AssetsCopy["Copy Assets"]:::build
        Static["_site (Static Output)"]:::infra
    end

    %% Hosting
    Hosting["Static Hosting\n(GitHub Pages/AWS/Cloudflare)"]:::infra

    %% Browser & Runtime
    subgraph "Browser / Client-Side"
        direction TB
        Browser["User Browser"]:::client
        PageLoad["Load HTML/CSS/JS"]:::client
        subgraph "Third-Party Services"
            direction TB
            EmailService["EmailJS API"]:::third
            GitalkService["Gitalk (GitHub Issues)"]:::third
            Clarity["Microsoft Clarity"]:::third
            CDN["CDNs\n(Google Fonts, HighlightJS,\nMathJax, Lodash)"]:::third
        end
    end

    %% Flows
    DeveloperEnv -->|push commits| GitHub
    GitHub -->|trigger build| Bundle
    Bundle --> Jekyll
    Jekyll --> Sass
    Sass --> AssetsCopy
    AssetsCopy --> Static
    Static --> Hosting
    Hosting --> Browser
    Browser --> PageLoad
    PageLoad --> EmailService
    PageLoad --> GitalkService
    PageLoad --> Clarity
    PageLoad --> CDN

    %% Click Events
    click Config "https://github.com/hyperzsb/natalia-theme/blob/master/_config.yaml"
    click Gemfile "https://github.com/hyperzsb/natalia-theme/tree/master/Gemfile"
    click GemfileLock "https://github.com/hyperzsb/natalia-theme/blob/master/Gemfile.lock"
    click Default "https://github.com/hyperzsb/natalia-theme/blob/master/_layouts/default.html"
    click PostLayout "https://github.com/hyperzsb/natalia-theme/blob/master/_layouts/post.html"
    click ProjectLayout "https://github.com/hyperzsb/natalia-theme/blob/master/_layouts/project.html"
    click Header "https://github.com/hyperzsb/natalia-theme/blob/master/_includes/header.html"
    click Footer "https://github.com/hyperzsb/natalia-theme/blob/master/_includes/footer.html"
    click TOC "https://github.com/hyperzsb/natalia-theme/blob/master/_includes/toc.html"
    click Loading "https://github.com/hyperzsb/natalia-theme/blob/master/_includes/loading.html"
    click Anchors "https://github.com/hyperzsb/natalia-theme/blob/master/_includes/anchor_headings.html"
    click Home "https://github.com/hyperzsb/natalia-theme/blob/master/_pages/home.html"
    click PostsPage "https://github.com/hyperzsb/natalia-theme/blob/master/_pages/posts.html"
    click ProjectsPage "https://github.com/hyperzsb/natalia-theme/blob/master/_pages/projects.html"
    click Contact "https://github.com/hyperzsb/natalia-theme/blob/master/_pages/contact.html"
    click NotFound "https://github.com/hyperzsb/natalia-theme/blob/master/_pages/404.html"
    click Post1 "https://github.com/hyperzsb/natalia-theme/blob/master/_posts/2022-03-03-post-1.md"
    click Post2 "https://github.com/hyperzsb/natalia-theme/blob/master/_posts/2022-03-04-post-2.md"
    click Post3 "https://github.com/hyperzsb/natalia-theme/blob/master/_posts/2022-03-05-post-3.md"
    click Post4 "https://github.com/hyperzsb/natalia-theme/blob/master/_posts/2022-03-06-post-4.md"
    click Project1 "https://github.com/hyperzsb/natalia-theme/blob/master/_projects/project-1.md"
    click Project2 "https://github.com/hyperzsb/natalia-theme/blob/master/_projects/project-2.md"
    click Project3 "https://github.com/hyperzsb/natalia-theme/blob/master/_projects/project-3.md"
    click Project4 "https://github.com/hyperzsb/natalia-theme/blob/master/_projects/project-4.md"
    click Bio "https://github.com/hyperzsb/natalia-theme/blob/master/_biographies/biography.md"
    click MainSCSS "https://github.com/hyperzsb/natalia-theme/blob/master/_sass/main.scss"
    click GitalkSCSS "https://github.com/hyperzsb/natalia-theme/blob/master/_sass/gitalk.scss"
    click MarkdownSCSS "https://github.com/hyperzsb/natalia-theme/blob/master/_sass/markdown.scss"
    click TocSCSS "https://github.com/hyperzsb/natalia-theme/blob/master/_sass/toc.scss"
    click MainJS "https://github.com/hyperzsb/natalia-theme/blob/master/assets/js/main.js"
    click DarkMode "https://github.com/hyperzsb/natalia-theme/blob/master/assets/js/dark-mode.js"
    click EmailJS "https://github.com/hyperzsb/natalia-theme/blob/master/assets/js/email.js"
    click UtilsJS "https://github.com/hyperzsb/natalia-theme/blob/master/assets/js/utils.js"

    %% Styles
    classDef build fill:#E8F1FF,stroke:#7AA7FF,stroke-width:1px
    classDef infra fill:#FFF4E5,stroke:#FFAA33,stroke-width:1px
    classDef client fill:#E6FFE6,stroke:#33CC33,stroke-width:1px
    classDef third fill:#FFE6E6,stroke:#FF3333,stroke-width:1px
    classDef actor fill:#F0F0F0,stroke:#999999,stroke-width:1px,stroke-dasharray: 5 5
```
