Skip to content

README.md

Latest commit

 

History

History
148 lines (113 loc) · 3.91 KB

README.md

File metadata and controls

148 lines (113 loc) · 3.91 KB

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.