Il Cotonificio Egg di Piedimonte Matese

Una Storia Industriale e Sociale Attraverso le Mappe

Overview

flowchart TD
    A["Archive (raw scans, notes)"] -->|curation| B["raw_data/*.md"]
    B -->|python pipeline| C[_photos/*.md]
    C -->|jekyll build| D[_site/]
    D -->|static HTML| E[Browser]
    E -->|frontmatter injected| F[myscript.js]
    F -->|reads config| G[Leaflet Map & Overlays]
    B -->|frontmatter| F
    C -->|frontmatter| F
    F -->|URL params| G

Historical material is first collected from archival scans, social-history contributions, and manual research notes, then normalized by an editor into one Markdown file per photo object inside raw_data/. Each raw_data entry represents a single historical record: descriptive text + structured metadata (date, labels, location geometry, and one primary image with optional variants). Original research material is stored in archive/, then curated to production level in raw_data/ as input to the python pipeline to produce jekyll collection items in _photos/.

This site is a static Jekyll project with a Python preprocessing pipeline and a client-side JavaScript data layer for interactive maps and overlays.

General Data Flow:

  1. Historical and research material is curated into Markdown files in raw_data/, each with YAML frontmatter for metadata (title, date, labels, location, images).
  2. The Python pipeline (scripts/process_research.py) processes these into normalized, runtime-ready Markdown in _photos/, generating image assets and GeoJSON overlays.
  3. Jekyll builds the static site, rendering pages from _photos/ and _topics/ collections.
  4. Client-side JavaScript (notably assets/js/myscript.js) powers interactive maps, overlays, and UI features, reading configuration from page frontmatter and URL parameters.

Key Principles:

JavaScript Data Flow and Frontmatter Integration

Overview

The main interactive logic is handled by assets/js/myscript.js, which powers the Leaflet-based maps and overlays on photo, topic, and map pages. This script is designed to:

How Frontmatter Drives JavaScript Behavior

flowchart LR
        subgraph Jekyll Build
            B1[raw_data/*.md] --frontmatter--> C1[_photos/*.md]
            C1 --frontmatter--> D1[HTML page]
        end
        D1 --JS vars--> E1[myscript.js]
        E1 --config merge--> F1[Map Initialization]
        F1 --overlays--> G1[Leaflet Map]
        E1 --URL params--> F1
        D1 --user interaction--> G1
        G1 --UI events--> E1

Jekyll layouts inject frontmatter variables as global JS variables (e.g., centerLat, centerLng, zoomLevel, activeLayers, topicSlug, topicFeaturedPhotos, photoOriginGeoJson, etc.). These are read by myscript.js at runtime to configure the map:

All these variables are set in the page’s HTML by the Jekyll layout, using Liquid templating to output the frontmatter values as JS assignments before loading myscript.js.

Data Flow in myscript.js

flowchart TD
        subgraph Page Render
            A1["Frontmatter (YAML)"] -->|Liquid| B1[JS Variables]
            B1 -->|window.*| C1[myscript.js]
            C1 -->|LAYER_CONFIG| D1[Map Layers]
            C1 -->|GeoJSON| E1[Photo Overlays]
            C1 -->|Timeline| F1[Slider Control]
        end
        C1 -->|reads URL| G1[URL Params]
        G1 -->|override| D1
        G1 -->|override| F1
        D1 -->|Leaflet| H1[Map]
        E1 -->|Leaflet| H1
        F1 -->|Leaflet| H1
  1. Configuration Merge: Reads global JS variables (from frontmatter) and merges with URL params for runtime config.
  2. Layer Setup: Builds a LAYER_CONFIG object for all map layers (basemaps, overlays, rasters, images, GeoJSON), using asset paths resolved from the Jekyll base URL.
  3. Map Initialization:
    • Creates the Leaflet map with the configured center/zoom.
    • Adds base and overlay layers as specified by config.
    • Loads GeoJSON overlays for photos, FOVs, and lines, filtering by topic or photo as needed.
    • Adds timeline slider if multiple historical rasters are present.
    • Adds custom controls (reset, opacity, fullscreen, geolocation, context menu).
  4. Frontmatter-Driven Overlays:
    • On photo pages, overlays are built from the location.*_geojson fields injected by the pipeline and passed via frontmatter.
    • On topic pages, overlays are filtered or loaded based on featured_photos and topic-specific GeoJSON.
  5. Error Handling: All resource loads are checked; missing or malformed data falls back to defaults and logs to the console.

Example: Passing Frontmatter to JS

In a Jekyll layout (e.g., _layouts/photo.html):

<script>
    var centerLat = 41.3551;
    var centerLng = 14.3722;
    var zoomLevel = 17;
    var activeLayers = null;
    var photoOriginGeoJson = null;
    // ...etc
</script>
<script src="/piedimonte-matese-old-photos/assets/js/myscript.js"></script>

Developer Notes

Markdown files frontmatter contains information to build the site ad the embedded leaflet maps :

The core pattern is:

  1. Curate source entries in raw_data/
  2. Run the Python pipeline (scripts/process_research.py)
  3. Build the site with Jekyll
  4. Serve generated output from _site/

The architecture is intentionally one-way: source data is edited in raw_data/, while _photos/ and generated assets are pipeline outputs.

Data Flow (Archive → Raw Data → _photos)

1) archive/ (private historical backup)

2) raw_data/ (authoritative editable source)

Current supported image schemas:

images:
    - file: "source-image.jpg"
        is_primary: true
        type: "original"
        note: "Main shot"
        alt: "Accessible alt text"

primary_image: "source-image.jpg"
variants:
    - file: "variant-image.jpg"
        type: "restoration"
        note: "Edited version"

3) _photos/ (generated Jekyll collection)

Generated media outputs:

Generated geospatial outputs:

Python Pipeline (scripts/process_research.py)

The script is an ETL pipeline for markdown metadata + image assets.

Processing stages

  1. Scan raw_data/*.md
  2. Parse frontmatter (python-frontmatter)
  3. Validate required keys (title, date, location, labels + image schema)
  4. Normalize image metadata to a unified images[] structure
  5. Optimize images and generate thumbnails (Pillow)
  6. Add location-derived GeoJSON to frontmatter
  7. Write generated _photos/[slug].md
  8. Aggregate all geometries into GeoJSON files (geopandas + shapely)

Frontmatter transformations

The script enriches metadata with runtime-ready fields, including:

Error and validation behavior

Execution

python scripts/process_research.py --log INFO

Useful dependencies (from requirements.txt):

Jekyll Collections and Rendering

photos collection

Photo layout behavior:

topics collection

Topic-photo join model:

Example featured_photos pattern:

featured_photos:
    - id: via-carmine-cotonificio
        commentary: "Historical relation to the square."

Labels System

Labels are not a separate Jekyll collection; they are derived from photo metadata.

Source

UI pages and behavior

Related list/table behavior:

Configuration and Runtime Dependencies

Central configuration

Client-side dependencies

Most dependencies are loaded from pinned CDN versions. This keeps the project compatible with static hosting and avoids a JS build pipeline.

Build and Deployment Model

Local developer flow

  1. Edit raw_data/ and/or _topics/
  2. Run scripts/process_research.py
  3. Run Jekyll build/serve
  4. Verify generated pages and map overlays

Output boundaries

This separation reduces drift and preserves reproducibility.

Notes for Technical Contributors