# masasam/emacs-easy-hugo architecture

> Architecture diagram of the GitHub repository masasam/emacs-easy-hugo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/masasam/emacs-easy-hugo
- Repository: https://github.com/masasam/emacs-easy-hugo

## Overview

##### Main Components
- Emacs Host
- Emacs core process
- Major-mode package:
– easy-hugo.el (core commands & file‐management logic)
– easy-hugo-transient.el (optional Transient UI)
- External Editors/Modes
- markdown-mode, org-mode, adoc-mode, rst-mode, mmark, web-mode
- Hugo Static-Site Generator (CLI)
- File System
- Hugo project directory (easy-hugo‐basedir)
– content/post (or content/home)
– static/images (easy-hugo-image-directory)
– archetypes/*.md/.org/.ad/.rst/.mmark/.html
– deploy.sh (when used)
- Search Backends
- consult-ripgrep, counsel-ag, helm-ag, the_silver_searcher
- Deployment Services/CLIs
- SSH/rsync (easy-hugo-publish via sshd)
- AWS CLI (amazon-s3)
- Google Cloud SDK (gcloud)
- Firebase CLI (firebase-tools)
- GitHub Pages (deploy.sh or GitHub Actions)
- Magit (Git commits for Netlify)
- Web Browser (Preview & Published Site)

##### Relationships & Data Flows
- User → Emacs Keybindings/Commands → easy-hugo.el
- easy-hugo.el → File System (create/edit .md/.org/.ad/… files)
- Preview: easy-hugo.el → Hugo CLI (hugo server) → HTTP → Browser
- Search: easy-hugo.el → consult-ripgrep / counsel-ag / helm-ag → results in Emacs buffer
- Publish/Clever: easy-hugo.el → chooses one of (SSH/rsync, AWS CLI, GCloud CLI, Firebase CLI, deploy.sh) → remote server or object storage → Browser (optional)
- Transient UI: easy-hugo-transient.el → wraps commands in pop-up menu → invokes core functions

##### Architectural Patterns
- Plugin Modularization:
- Core “model” layer = file and Hugo‐CLI interactions
- Controller = command functions bound to keys
- View = Emacs buffers + Transient menus
- Strategy/Provider Pattern for deployment:
- easy-hugo-publish-clever dynamically selects the deployment strategy based on which variables/CLIs are configured
- Extension Points:
- Hooks & user variables (easy-hugo-basedir, easy-hugo-image-directory, easy-hugo-default-ext, etc.)
- Pluggable search backends and markup modes

##### Technologies & Libraries
- Emacs Lisp & Cask (package metadata)
- transient (optional interactive menus)
- markdown-mode, org-mode, web-mode, AsciiDoc, reStructuredText, mmark
- consult-ripgrep / counsel-ag / helm-ag / the_silver_searcher
- Hugo binary (v0.25+)
- AWS CLI, Google Cloud SDK, Firebase Tools, SSH/Rsync, GitHub Actions, Magit

##### Detail Without Overthinking
- Post creation
- Preview server management
- Publish & deploy strategies
- Search integration
- Image insertion & upload
- How Transient UI wraps core functions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Emacs Host and Plugin
    EmacsCore["Emacs Core Process"]:::emacs
    subgraph "Emacs Plugin"
        easyHugo["easy-hugo.el\n(core commands & file management)"]:::emacs
        transient["easy-hugo-transient.el\n(Transient UI)"]:::emacs
        CaskNode["Cask\n(package metadata)"]:::docs
        README["README.md"]:::docs
        LICENSENode["LICENSE"]:::docs
        gitignore[".gitignore"]:::docs
    end

    %% File System
    subgraph "File System" 
        projectDir["Hugo Project Dir\n(easy-hugo-basedir)"]:::fileSystem
        content["content/post\nor content/home"]:::fileSystem
        images["static/images"]:::fileSystem
        archetypes["archetypes/*.md/.org/.ad/.rst/.mmark/.html"]:::fileSystem
        deployScript["deploy.sh"]:::fileSystem
        noteFS["(easy-hugo-image-directory)"]:::fileSystem
    end

    %% Hugo CLI
    HugoCLI["Hugo CLI"]:::cli

    %% Search Backends
    subgraph "Search Backends"
        ripgrep["consult-ripgrep"]:::search
        counsel["counsel-ag"]:::search
        helmag["helm-ag"]:::search
        silver["the_silver_searcher"]:::search
    end

    %% Deployment Services
    subgraph "Deployment Services"
        ssh["SSH/Rsync"]:::deploy
        aws["AWS CLI"]:::deploy
        gcloud["Google Cloud SDK"]:::deploy
        firebase["Firebase CLI"]:::deploy
        ghpages["GitHub Pages"]:::deploy
        magit["Magit"]:::deploy
    end

    %% Browser
    Browser["Web Browser\n(Preview & Site)"]:::browser

    %% Relationships
    EmacsCore --> easyHugo
    easyHugo -->|"create/edit posts"| content
    easyHugo -->|"insert/upload image"| images
    easyHugo -->|"start server"| HugoCLI
    HugoCLI -->|"HTTP preview"| Browser
    easyHugo ---|"ripgrep search"| ripgrep
    easyHugo ---|"counsel search"| counsel
    easyHugo ---|"helm search"| helmag
    easyHugo ---|"ag search"| silver
    easyHugo ---|"publish"| ssh
    easyHugo ---|"publish"| aws
    easyHugo ---|"publish"| gcloud
    easyHugo ---|"publish"| firebase
    easyHugo ---|"publish"| ghpages
    easyHugo ---|"publish"| magit
    transient -->|"wraps commands"| easyHugo

    %% Click Events
    click easyHugo "https://github.com/masasam/emacs-easy-hugo/blob/master/easy-hugo.el"
    click transient "https://github.com/masasam/emacs-easy-hugo/blob/master/easy-hugo-transient.el"
    click CaskNode "https://github.com/masasam/emacs-easy-hugo/tree/master/Cask"
    click README "https://github.com/masasam/emacs-easy-hugo/blob/master/README.md"
    click LICENSENode "https://github.com/masasam/emacs-easy-hugo/tree/master/LICENSE"
    click images "https://github.com/masasam/emacs-easy-hugo/tree/master/image"
    click gitignore "https://github.com/masasam/emacs-easy-hugo/blob/master/.gitignore"

    %% Styles
    classDef emacs fill:#cfe2f3,stroke:#333,stroke-width:1px;
    classDef fileSystem fill:#e0e0e0,stroke:#333,stroke-width:1px;
    classDef cli fill:#d5eadf,stroke:#333,stroke-width:1px;
    classDef deploy fill:#fde2bf,stroke:#333,stroke-width:1px;
    classDef search fill:#e4d5f7,stroke:#333,stroke-width:1px;
    classDef browser fill:#fff2cc,stroke:#333,stroke-width:1px;
    classDef docs fill:#f3e2f1,stroke:#333,stroke-width:1px;
```
