timeline-generator

name	timeline-generator
description	This skill generates interactive timeline visualizations using the vis-timeline JavaScript library. Use this skill when users need to create historical timelines, project timelines, event sequences, or any chronological data visualization with optional category filtering. The skill creates a complete MicroSim package with HTML, CSS, JSON data, and documentation.

Timeline Generator

Overview

This skill generates professional, interactive timeline visualizations using vis-timeline.js. Timelines are ideal for displaying chronological events with rich context including descriptions, notes, and category groupings. The skill creates a complete MicroSim package suitable for embedding in educational content or documentation sites built with MkDocs.

When to Use This Skill

Use this skill when users request:

• Historical timelines: Family histories, organizational milestones, historical periods
• Project timelines: Development phases, product roadmaps, release schedules
• Event sequences: Course schedules, curriculum timelines, process flows
• Category-based timelines: Multi-track timelines with filtering capabilities
• Interactive visualizations: Need for hover tooltips, clickable events, zoom/pan navigation

Common trigger phrases:

• "Create a timeline showing..."
• "Visualize the history of..."
• "Build an interactive timeline for..."
• "Show chronological events for..."

Workflow

Step 1: Gather Timeline Requirements

Before generating the timeline, collect information about:

1. Timeline content:

   • What is the subject/title of the timeline?
   • What time period does it cover?
   • What are the specific events to display?

2. Event data (for each event):

   • Event headline/title (required)
   • Date (year, month, day - year is required)
   • Description text (required)
   • Category/group (optional, for filtering)
   • Historical context notes (optional, for tooltips)

3. Category filtering:

   • Ask: "Would you like category filter buttons in the viewer?"
   • If yes, gather category names and colors
   • If not provided, create logical categories from the event data

4. Integration context:

   • Standalone page
   • Embedded in MkDocs documentation
   • Part of educational content

IMPORTANT: If the user has not provided a specific event list, prompt them:

"I'll create an interactive timeline for you. Please provide the events you'd like to include with:

• Event title/headline
• Date (at least the year)
• Description
• Category (optional)
• Any additional context notes for tooltips (optional)

Would you also like category filter buttons to allow viewing specific types of events?"

Step 2: Create Directory Structure

Create a new directory for the MicroSim following this pattern:

docs/sims/<timeline-name>/
├── main.html         # Main visualization file
├── timeline.json     # Event data in TimelineJS format
└── index.md          # Documentation (if part of MkDocs)

Naming convention: Use kebab-case (lowercase with hyphens) for directory names that are descriptive and URL-friendly (e.g., project-history-timeline, course-schedule, family-heritage-timeline).

Step 3: Create timeline.json Data File

Generate a JSON file following this structure:

{
  "title": "Timeline Title",
  "events": [
    {
      "start_date": {
        "year": "2024",
        "month": "1",
        "day": "15",
        "display_date": "January 15, 2024"
      },
      "text": {
        "headline": "Event Title",
        "text": "Detailed description of the event."
      },
      "group": "Category Name",
      "notes": "Additional context that appears in the tooltip."
    }
  ]
}

Key data structure notes:

• year is required in start_date
• month and day are optional (default to 1 if omitted)
• display_date is optional (for custom date formatting)
• group is the category used for filtering
• notes provides tooltip/hover text with additional context
• All text fields support basic HTML formatting

Data preparation guidelines:

1. Sort events chronologically (oldest to newest)
2. Use consistent category names across related events
3. Keep headlines concise (5-10 words)
4. Provide substantive descriptions (2-4 sentences)
5. Add historical context in notes for educational value

Step 4: Create main.html with vis-timeline

Generate the main HTML file with the following structure:

1. HTML boilerplate with proper meta tags
2. vis-timeline CDN imports:
   • JS: https://cdnjs.cloudflare.com/ajax/libs/vis-timeline/7.7.3/vis-timeline-graph2d.min.js
   • CSS: https://cdnjs.cloudflare.com/ajax/libs/vis-timeline/7.7.3/vis-timeline-graph2d.min.css
3. Styled header with timeline title and subtitle
4. Category filter controls (if requested)
5. Timeline container div
6. Info panel with legend and event details
7. JavaScript implementation:
   • Load timeline.json data
   • Convert to vis-timeline format
   • Create color scheme for categories
   • Initialize timeline with options
   • Implement category filtering
   • Handle event selection for detail display

Key vis-timeline configuration elements:

// Color scheme for categories
const categoryColors = {
    'Category 1': '#color1',
    'Category 2': '#color2',
    // ... more categories
};

// Convert JSON events to vis-timeline format
allItems = data.events.map((event, index) => {
    const year = event.start_date.year;
    const month = event.start_date.month || 1;
    const day = event.start_date.day || 1;
    const startDate = new Date(parseInt(year), month - 1, day);

    return {
        id: `event-${index}`,
        content: event.text.headline,
        start: startDate,
        title: event.notes || event.text.headline,
        className: event.group.replace(/\s+/g, '-').toLowerCase(),
        style: `background-color: ${categoryColors[event.group]}; color: white;`,
        category: event.group,
        eventData: event
    };
});

// Timeline options
const options = {
    width: '100%',
    height: '600px',
    margin: { item: 20, axis: 40 },
    orientation: 'top',
    zoomMin: 1000 * 60 * 60 * 24 * 365 * 10,  // 10 years
    zoomMax: 1000 * 60 * 60 * 24 * 365 * 1200, // 1200 years
    tooltip: {
        followMouse: true,
        template: function(item) {
            return item.notes || '';
        }
    },
    stack: true,
    selectable: true
};

Important implementation features:

1. Category filtering: Filter button implementation

   function filterCategory(category) {
       if (category === 'all') {
           timelineData.clear();
           timelineData.add(allItems);
       } else {
           const filtered = allItems.filter(item => item.category === category);
           timelineData.clear();
           timelineData.add(filtered);
       }
       timeline.fit();
   }
   

2. Event detail display: Show full event information on click

   timeline.on('select', function(properties) {
       if (properties.items.length > 0) {
           showEventDetails(properties.items[0]);
       }
   });
   

3. Color-coded events: Apply category colors to timeline items

4. Responsive tooltips: Show context notes on hover

5. Legend display: Visual guide for category colors

Design considerations:

• Use a professional color scheme (distinct, accessible colors)
• Provide clear visual hierarchy
• Ensure text readability against colored backgrounds
• Include hover effects for interactivity
• Make the layout responsive for different screen sizes

Step 5: Create index.md Documentation

If the timeline is part of a MkDocs site, create comprehensive documentation:

# [Timeline Title]

[Brief description of what this timeline visualizes]

[Run the [Timeline Name]](./main.html)

[View the Raw Timeline Data](timeline.json)

## Overview

[Detailed explanation of the timeline's purpose, content, and coverage]

## Features

### Interactive Elements
- **Zoom and Pan**: Click and drag to pan, scroll to zoom in/out
- **Event Details**: Click any event to see full details below the timeline
- **Hover Tooltips**: Hover over events to see historical context notes
- **Category Filtering**: Use filter buttons to view specific event categories

### Visual Design
- **Color-coded categories**: Each event category has a distinct color
- **Responsive layout**: Works on desktop, tablet, and mobile devices
- **Legend**: Visual guide showing category colors and meanings

## Data Structure

The timeline data is stored in `timeline.json` following this format:

[Include JSON structure example]

## Customization Guide

### Adding New Events

1. Open `timeline.json`
2. Add a new event object to the `events` array
3. Reload the page to see your changes

### Changing Colors

To modify category colors, edit the `categoryColors` object in `main.html`:

[Code example]

### Adjusting Time Range

To change the zoom limits, modify the `zoomMin` and `zoomMax` options:

[Code example]

## Technical Details

- **Timeline Library**: vis-timeline 7.7.3
- **Data Format**: TimelineJS-compatible JSON
- **Browser Compatibility**: Modern browsers (Chrome, Firefox, Safari, Edge)
- **Dependencies**: vis-timeline.js (loaded from CDN)

## Use Cases

This timeline pattern can be adapted for:
- Historical education
- Project planning and tracking
- Course schedules and curricula
- Organizational history
- Personal timelines and biographies

Documentation best practices:

1. Provide clear usage instructions
2. Include code examples for common customizations
3. Explain the data format thoroughly
4. Link to external resources (vis-timeline docs)
5. Suggest related use cases

Step 6: Integrate into Navigation (MkDocs)

If using MkDocs, add the timeline to the navigation in mkdocs.yml:

nav:
  - MicroSims:
      - Introduction: sims/index.md
      - [Timeline Name]: sims/[timeline-name]/index.md
      - [Other sims...]: ...

Place the entry in a logical position based on:

• Related content (group similar visualizations)
• Alphabetical order
• Chronological order of creation

Step 7: Test and Validate

Before considering the timeline complete:

1. Data validation:

   • Verify timeline.json is valid JSON
   • Check all dates parse correctly
   • Confirm all events have required fields
   • Validate category names are consistent

2. Visual testing:

   • Open main.html directly in browser
   • Test with mkdocs serve if applicable
   • Check timeline spans entire date range
   • Verify all events are visible and properly spaced
   • Test on different screen sizes

3. Interactive testing:

   • Zoom in/out to verify scale limits
   • Pan across the full timeline
   • Hover over events to check tooltips
   • Click events to verify detail display
   • Test category filter buttons (if present)
   • Check "All Events" filter restores full view

4. Content review:

   • Proofread all event text
   • Verify historical accuracy
   • Check that context notes provide value
   • Ensure descriptions are complete

5. Browser compatibility:

   • Test on Chrome, Firefox, Safari, Edge
   • Verify CDN resources load correctly
   • Check console for JavaScript errors

Best Practices

Data Preparation

1. Date accuracy: Use precise dates when available
2. Chronological order: Sort events in JSON for easier maintenance
3. Consistent categories: Use standardized category names
4. Rich context: Provide substantive descriptions and notes
5. Source validation: Verify historical facts and dates

Category Design

1. Limit categories: 3-6 categories works best for filtering
2. Meaningful groupings: Categories should reflect natural divisions
3. Balanced distribution: Aim for relatively even event distribution
4. Clear naming: Use descriptive, non-overlapping category names
5. Color accessibility: Choose colors with sufficient contrast

Visual Design

1. Color coding: Use distinct, visually appealing colors
2. Text readability: Ensure white text on colored backgrounds is clear
3. Legend placement: Make the legend visible and understandable
4. Responsive sizing: Timeline should work on all screen sizes
5. Loading states: Consider showing a loading indicator

Documentation

1. Usage examples: Show how to interact with the timeline
2. Data format: Clearly document the JSON structure
3. Customization: Provide code snippets for common changes
4. Attribution: Credit data sources when appropriate
5. Educational context: Explain why the timeline matters

MkDocs Integration

1. Direct linking: Provide links to both main.html and timeline.json
2. Iframe embedding: Can use iframe for inline display if desired
3. Navigation placement: Group with related content
4. Cross-references: Link to related pages or timelines

Common Variations

Simple Timeline (No Categories)

Omit the category filtering UI and use a single color:

const categoryColors = {
    'Default': '#2d5016'
};

Vertical Timeline

Change orientation for a vertical layout:

options: {
    orientation: 'left'  // or 'right'
}

Range Events

For events with duration, add an end_date:

{
  "start_date": {"year": "2020", "month": "1"},
  "end_date": {"year": "2021", "month": "12"},
  "text": {"headline": "Multi-year Project"}
}

Embedded Media

Add images or videos to events (requires additional configuration).

Troubleshooting

Timeline Not Displaying

Solution: Check browser console for errors, verify timeline.json loads correctly, ensure CDN resources are accessible.

Events Overlapping

Solution: Increase margin.item value in options or enable stack: true for automatic vertical stacking.

Zoom Too Fast/Slow

Solution: Adjust zoomMin and zoomMax values based on your date range.

Filter Buttons Not Working

Solution: Verify category names match exactly between JSON data and filter buttons, check JavaScript console for errors.

Dates Parsing Incorrectly

Solution: Ensure month values are 1-12, not 0-11. The conversion to JavaScript Date handles this in the code.

References

This skill uses the following assets and references:

Assets

• vis-timeline CDN:
  • JS: https://cdnjs.cloudflare.com/ajax/libs/vis-timeline/7.7.3/vis-timeline-graph2d.min.js
  • CSS: https://cdnjs.cloudflare.com/ajax/libs/vis-timeline/7.7.3/vis-timeline-graph2d.min.css
• No local assets required (vis-timeline loaded from CDN)

References

• vis-timeline Documentation
• TimelineJS3 Data Format (compatible structure)
• vis-timeline GitHub Repository

Example Implementation

See the timeline example at /docs/sims/timeline/ for a complete reference implementation showcasing McCreary family heritage timeline.

License

This skill is provided under the same license as the claude-skills repository. The vis-timeline library is licensed under Apache-2.0/MIT dual license.