# maximevaillancourt/digital-garden-jekyll-template architecture

> Architecture diagram of the GitHub repository maximevaillancourt/digital-garden-jekyll-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maximevaillancourt/digital-garden-jekyll-template
- Repository: https://github.com/maximevaillancourt/digital-garden-jekyll-template

## Overview

##### Project type and purpose
- This is a **Jekyll-based static site generator template** designed to power a “digital garden” (interlinked Markdown notes, Roam-style double brackets, backlinks graph).
- Its main goal is to transform a folder of Markdown notes and pages into a static website with custom plugins (bidirectional link generator, embed-tweet, etc.), Sass styling, and deploy it (Netlify or GitHub Pages via GitHub Actions).

##### File structure
- Top-level config & CI/CD:
- _config.yml – core Jekyll settings
- Gemfile / Gemfile.lock – Ruby + Jekyll + plugin dependencies
- netlify.toml – Netlify build & deploy instructions
- .github/workflows/jekyll.yml – GitHub Actions CI for building & deploying to GitHub Pages
- Content directories:
- _notes/ – Markdown files for each note (includes nested subfolders)
- _pages/ – site-level pages (about, index)
- Theming & templating:
- _layouts/ – HTML templates (default, page, note)
- _includes/ – partials (nav, footer, graph script, link-preview)
- _sass/ & styles.scss – styling, partial Sass files
- assets/ – media (e.g., MP3)
- Custom plugins:
- _plugins/*.rb – Ruby scripts that run during Jekyll build (generate bidirectional_links, graph JSON, last_modified, external link handling, etc.)

##### Additional insights from README
- Highlights interactive notes graph powered by a JSON file generated at build time.

a. Main components
1) Content store (Markdown in _notes & _pages)
2) Jekyll build engine (reads config, content, layouts, includes, Sass, plugins)
3) Custom plugin layer (Ruby classes generating notes_graph.json, backlinks, etc.)
4) Theming layer (layouts + includes + Sass → CSS)
5) Build artifacts (static HTML, CSS, JS, graph JSON)
6) Deployment targets (Netlify or GitHub Pages via GitHub Actions)
7) External services (Netlify CDN, GitHub repo)

b. Relationships & interactions
- Content store + _config.yml feed into Jekyll core
- Jekyll invokes custom plugins during the “generate” phase → outputs notes_graph.json and augments pages with backlinks
- Jekyll processes Sass → compiles CSS
- Layouts + includes template content → produce final HTML files
- Build artifacts get pushed to hosting (via Netlify CLI or GitHub Actions workflow)
- Hosting/CDN serves static assets to end users; graph JSON consumed by client-side graph visualization script

c. Architectural patterns & design principles
- **Static-site generator pipeline**: Clear separation of source content → build → deploy → serve
- **Plugin-based extensibility**: Ruby plugin scripts hook into Jekyll lifecycle events
- **Modular theming**: Reusable partials (_includes), layouts, Sass partials
- **Content-centric design**: notes organized in hierarchies, double-bracket linking, automatic graph data

d. Relevant technologies / frameworks
- Ruby & Jekyll core
- Custom Ruby plugins
- Liquid templating (layouts & includes)
- Sass (via Jekyll’s Sass converter)
- GitHub Actions (.github/workflows/jekyll.yml)
- Netlify (netlify.toml)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Content Store
    subgraph "Content Store"
        CSN["_notes/"]:::developer
        CSP["_pages/"]:::developer
    end
    click CSN "https://github.com/maximevaillancourt/digital-garden-jekyll-template/tree/main/_notes/"
    click CSP "https://github.com/maximevaillancourt/digital-garden-jekyll-template/tree/main/_pages/"

    %% Configuration & Dependencies
    Config["_config.yml"]:::developer
    Gemfile["Gemfile"]:::developer
    Gemlock["Gemfile.lock"]:::developer
    click Config "https://github.com/maximevaillancourt/digital-garden-jekyll-template/blob/main/_config.yml"
    click Gemfile "https://github.com/maximevaillancourt/digital-garden-jekyll-template/tree/main/Gemfile"
    click Gemlock "https://github.com/maximevaillancourt/digital-garden-jekyll-template/blob/main/Gemfile.lock"

    %% Jekyll Core
    JCore["Jekyll Core"]:::build

    %% Custom Plugins
    subgraph "Custom Plugin Layer"
        P1["bidirectional_links_generator.rb"]:::developer
        P2["embed_tweets.rb"]:::developer
        P3["empty_front_matter_note_injector.rb"]:::developer
        P4["last_modified_at_generator.rb"]:::developer
        P5["markdown-highlighter.rb"]:::developer
        P6["open_external_links_in_new_tab.rb"]:::developer
    end
    click P1 "https://github.com/maximevaillancourt/digital-garden-jekyll-template/blob/main/_plugins/bidirectional_links_generator.rb"
    click P2 "https://github.com/maximevaillancourt/digital-garden-jekyll-template/blob/main/_plugins/embed_tweets.rb"
    click P3 "https://github.com/maximevaillancourt/digital-garden-jekyll-template/blob/main/_plugins/empty_front_matter_note_injector.rb"
    click P4 "https://github.com/maximevaillancourt/digital-garden-jekyll-template/blob/main/_plugins/last_modified_at_generator.rb"
    click P5 "https://github.com/maximevaillancourt/digital-garden-jekyll-template/blob/main/_plugins/markdown-highlighter.rb"
    click P6 "https://github.com/maximevaillancourt/digital-garden-jekyll-template/blob/main/_plugins/open_external_links_in_new_tab.rb"

    %% Theming Layer
    subgraph "Theming Layer"
        LayoutDir["_layouts/"]:::developer
        IncludeDir["_includes/"]:::developer
        SassEntry["styles.scss"]:::developer
        Sass1["_sass/_normalize.scss"]:::developer
        Sass2["_sass/_code.scss"]:::developer
        Sass3["_sass/_style.scss"]:::developer
    end
    click LayoutDir "https://github.com/maximevaillancourt/digital-garden-jekyll-template/tree/main/_layouts/"
    click IncludeDir "https://github.com/maximevaillancourt/digital-garden-jekyll-template/tree/main/_includes/"
    click SassEntry "https://github.com/maximevaillancourt/digital-garden-jekyll-template/blob/main/styles.scss"
    click Sass1 "https://github.com/maximevaillancourt/digital-garden-jekyll-template/blob/main/_sass/_normalize.scss"
    click Sass2 "https://github.com/maximevaillancourt/digital-garden-jekyll-template/blob/main/_sass/_code.scss"
    click Sass3 "https://github.com/maximevaillancourt/digital-garden-jekyll-template/blob/main/_sass/_style.scss"

    %% Static Assets
    Assets["assets/"]:::developer
    click Assets "https://github.com/maximevaillancourt/digital-garden-jekyll-template/tree/main/assets/"

    %% Build Artifacts
    subgraph "Build Artifacts"
        HTML["Static HTML"]:::artifact
        CSS["CSS"]:::artifact
        JSON["notes_graph.json"]:::artifact
        JS["Client-side JS"]:::artifact
    end

    %% Deployment
    subgraph "Deployment Targets"
        Netlify["Netlify"]:::deploy
        GHA["GitHub Actions"]:::deploy
    end
    click Netlify "https://github.com/maximevaillancourt/digital-garden-jekyll-template/blob/main/netlify.toml"
    click GHA "https://github.com/maximevaillancourt/digital-garden-jekyll-template/blob/main/.github/workflows/jekyll.yml"

    %% Project Metadata
    subgraph "Project Metadata"
        Funding[".github/FUNDING.yml"]:::developer
        Issues[".github/ISSUE_TEMPLATE/"]:::developer
        Page404["404.html"]:::developer
    end
    click Funding "https://github.com/maximevaillancourt/digital-garden-jekyll-template/blob/main/.github/FUNDING.yml"
    click Issues "https://github.com/maximevaillancourt/digital-garden-jekyll-template/tree/main/.github/ISSUE_TEMPLATE/"
    click Page404 "https://github.com/maximevaillancourt/digital-garden-jekyll-template/blob/main/404.html"

    %% End User
    User["End-User Browser"]:::external

    %% Connections
    CSN -->|source content| JCore
    CSP -->|source content| JCore
    Config -->|Jekyll settings| JCore
    Gemfile -->|dependencies| JCore
    Gemlock -->|dependencies| JCore

    JCore -->|invoke plugins| P1
    JCore -->|invoke plugins| P2
    JCore -->|invoke plugins| P3
    JCore -->|invoke plugins| P4
    JCore -->|invoke plugins| P5
    JCore -->|invoke plugins| P6

    JCore -->|use layouts/includes| LayoutDir
    JCore -->|use layouts/includes| IncludeDir
    JCore -->|compile Sass| SassEntry

    P1 -->|generate JSON| JSON
    P2 -->|embed tweets| HTML
    P3 -->|ensure front matter| HTML
    P4 -->|add last modified| HTML
    P5 -->|highlight code| HTML
    P6 -->|external links target| HTML

    SassEntry -->|Sass compile| CSS
    LayoutDir -->|Liquid render| HTML
    IncludeDir -->|Liquid render| HTML
    Assets -->|copy assets| HTML

    JCore -->|render HTML/JSON/JS| HTML
    JCore -->|render CSS| CSS
    JCore -->|output JSON| JSON
    JCore -->|bundle JS| JS

    HTML -->|deploy via Netlify CLI| Netlify
    CSS -->|deploy via Netlify CLI| Netlify
    JSON -->|deploy via Netlify CLI| Netlify
    JS -->|deploy via Netlify CLI| Netlify

    HTML -->|deploy via GH Actions| GHA
    CSS -->|deploy via GH Actions| GHA
    JSON -->|deploy via GH Actions| GHA
    JS -->|deploy via GH Actions| GHA

    Netlify -->|serve HTTP| User
    GHA -->|serve HTTP via GH Pages| User
    User -->|fetch notes_graph.json| JSON

    %% Styles
    classDef developer fill:#E3F2FD,stroke:#1976D2,stroke-width:1px
    classDef build fill:#C8E6C9,stroke:#2E7D32,stroke-width:1px
    classDef deploy fill:#FFE0B2,stroke:#EF6C00,stroke-width:1px
    classDef artifact fill:#EEEEEE,stroke:#9E9E9E,stroke-width:1px
    classDef external fill:#F5F5F5,stroke:#616161,stroke-width:1px
```
