How vivasmaq/disploy works
Project Type and Purpose
• This is a command-line static site generator written in Bash, tailored for photoessays.
• It watches a directory tree of images, videos, and text/metadata files, processes them (with ImageMagick, FFmpeg, a sed-based YAML parser, and a bundled Markdown script), applies HTML templates from a chosen theme, and emits a fully static site under a “_site” folder.
Key Architectural Components
a. User Environment
• Terminal / Shell (Bash, Cygwin, OS X, Linux)
• External Dependencies:
– ImageMagick (image processing)
– FFmpeg (video encoding/filtering)
b. expose.sh Orchestrator
– Entry point script.
– Walks the working directory tree (recursively).
– Filters out underscored items.
– Sorts folders/files alphabetically (with optional numeric prefixes).
– For each folder and media item:
• Parses per-folder metadata.txt (optional)
• Parses per-item YAML from sidecar .txt files (via sed regex)
c. Processing Modules
– Image Module
• Reads raw images, generates resized derivatives (e.g., 640.jpg, etc.)
• Applies global/static image-options filters via ImageMagick CLI.
– Video Module
• Converts image sequences to video if folder named “imagesequence”.
• Transcodes each video at configured resolutions and codecs.
• Applies video-options and video-filters via FFmpeg.
• Extracts poster images.
– Markdown Module
• Bundled Markdown.pl script for any text rendering (if used).
d. Templating Engine
– Sed-based simple variable substitution in two template files per theme:
• template.html (global page shell, navigation/menu)
• post-template.html (per-item HTML fragment)
– Supplies built-in variables ({{gallerytitle}}, {{navigation}}, etc.) + YAML metadata.
e. Themes (theme1, theme2, custom)
– Contain CSS, JS, img assets, plus the two HTML templates.
– Copied wholesale into output alongside generated HTML.
f. Output Generator
– Builds a mirrored directory tree under “_site” with:
• index.html at each gallery level (using template.html)
• Per-item pages or inline fragments (via post-template.html)
• Resized images and videos in resolution/codec-named files
• Asset directories for CSS/JS/images
Relationships & Data Flow
1. User runs expose.sh in a source folder.
2. expose.sh → reads folder structure + metadata → feeds file-by-file to processing modules.
3. Processing modules (ImageMagick, FFmpeg, Markdown.pl) transform media/text → output into a staging “_site” tree.
4. Templating engine molds processed assets into HTML, inserting navigation, titles, and per-item content.
5. Theme assets are copied into the output.
6. Final static site is ready for deployment (no further runtime dependencies).
Architectural Patterns & Principles
• Pipeline/Orchestration: expose.sh drives a linear series of transforms.
• Convention-over-Configuration: folder names, file naming patterns, and YAML sidecars encode behavior.
• Pluggable Themes: separation of logic (script) from presentation (templates + assets).
• Extensibility Points:
• Adding new theme directories.
• Tuning sed-based YAML parser for extra keys.
• Hooking into ImageMagick/FFmpeg filter flags.
Essential Elements
• Processing modules under the expose.sh umbrella
• External dependencies off to one side
• Input source folder vs. output _site folder
• Theme asset copy step