Weaving Histories

A Jekyll-based digital storytelling platform for creating interactive narratives with maps, timelines, and multimedia content.

Overview

Weaving Histories is a scrollable storytelling framework that combines:

• Interactive maps with zoom and pan navigation using Leaflet.js
• Timeline visualizations for chronological narratives
• Video integration with YouTube embeds
• Multi-layered content with expandable information panels

Getting Started

Prerequisites

• Ruby (see .ruby-version for the specific version)
• Bundler gem

Installation

bundle install

Development

Start the local Jekyll server:

bundle exec jekyll serve

The site will be available at http://localhost:4000/weaving_history/

Note: If you modify _config.yml, you must restart the server for changes to take effect.

Creating Stories

Story Structure

Stories are defined in _data/story.json as an array of step objects. Each step represents a scroll position that triggers different media views and content.

Story Step Format

{
  "id": 1,
  "question": "The main question or title for this step",
  "answer": "Brief introductory text visible in the scroll panel",
  "view": "map",
  "media": {
    "type": "map-image",
    "src": "/assets/images/your-image.jpg",
    "width": 2048,
    "height": 1364
  },
  "x": 1024,
  "y": 682,
  "zoom": 0,
  "pins": [
    "900|600|Point A description",
    "1020|720|Point B description"
  ],
  "layer1": {
    "title": "Additional Information",
    "text": "Detailed content that appears in an offcanvas panel",
    "media": "/assets/images/layer1-image.jpg"
  },
  "layer2": {
    "title": "More Context",
    "text": "Further details in a stacked panel",
    "media": "/assets/images/layer2-image.jpg"
  }
}

View Types

• map: Interactive image map with pan/zoom
• timeline: Embedded timeline visualization
• video: YouTube video player

Media Types

• map-image: Static image overlay (requires width and height)
• map-tile: Tile layer for geographic maps
• video: YouTube video (include start time in seconds if needed)

Coordinate System

The map uses Leaflet's CRS.Simple projection for static images:

• Origin [0, 0] is the top-left corner
• x and y values position the camera center
• zoom levels: negative values zoom out, positive values zoom in
• Pins use x|y|label format where coordinates match the image dimensions

Project Structure

weaving_history/
├── _config.yml           # Jekyll configuration
├── _data/
│   └── story.json        # Story content and structure
├── _includes/
│   ├── story/
│   │   ├── adapter.html  # JSON to HTML renderer
│   │   ├── step.html     # Individual step template
│   │   └── panel-*.html  # Content layer templates
│   ├── head.html
│   ├── header.html
│   └── footer.html
├── _layouts/
│   ├── story.html        # Main story layout
│   └── page.html
├── _stories/
│   └── *.md              # Story markdown files
├── assets/
│   ├── css/
│   ├── js/
│   │   ├── story.js      # Main storytelling runtime
│   │   └── leaflet-iiif.js
│   └── images/           # Story images
└── Gemfile

Key Technologies

• Jekyll 4.3.4: Static site generator
• Bootstrap 5.3: UI framework with offcanvas panels
• Leaflet 1.9.4: Interactive map library
• Scrollama: Scroll-driven interactions
• YouTube IFrame API: Video playback

Configuration

Edit _config.yml to customize:

• title: Site title
• description: Site description
• baseurl: Path prefix for GitHub Pages deployment
• url: Full site URL

Deployment

This site is configured for GitHub Pages deployment. The baseurl setting in _config.yml should match your repository name.