@jaydixit/transitpaths

A flexible timeline component for Astro projects with itinerary parsing, chronological sequencing, and location tracking.

Features

• 📅 MDX/Markdown Parsing: Parse itinerary files with dates, locations, and activities
• 🗓️ Chronological Sequencing: Automatic chronological ordering of events
• 📍 Location Tracking: Track current location based on date
• ✈️ Transit Visualization: Beautiful transit event displays (flights, trains, driving)
• ✅ Todo Management: Support for todo items with completion tracking
• 🎨 Customizable Themes: Multiple built-in themes and custom styling
• 📱 Responsive Design: Mobile-optimized layout
• 🔧 Flexible Configuration: Extensive customization options

Installation

npm install @jaydixit/transitpaths
# or
yarn add @jaydixit/transitpaths
# or
pnpm add @jaydixit/transitpaths

Basic Usage

Using the Timeline Component

---
// pages/itinerary.astro
import Timeline from '@jaydixit/transitpaths/src/components/Timeline.astro';
import itineraryContent from './my-itinerary.mdx?raw';

const config = {
  theme: 'default',
  features: {
    calendar: true,
    currentLocation: true,
    navigation: true,
    todoItems: true,
    autoScrollToToday: true
  }
};
---

<Timeline mdxContent={itineraryContent} config={config} />

MDX File Format

Create your itinerary in MDX format:

---
title: Summer Travel 2025
excerpt: My travel plans for summer
---

# Summer European Adventure

## July 26

- fly Brooklyn ➔ Edinburgh

## July 27

Arrive Edinburgh

## August 1

- Edinburgh Fringe Festival opening
- [ ] Buy tickets for shows
- [x] Book accommodation

## August 5

- train Edinburgh ➔ Milan

## August 6 -- August 10

Milan Fashion Week activities

Advanced Usage

Using with Custom Data

---
import Timeline from '@jaydixit/transitpaths/src/components/Timeline.astro';
import { buildChronoEvents } from '@jaydixit/transitpaths';

// Build your own event data
const myEvents = buildChronoEvents(timelineData, locationConfig);

const config = {
  theme: 'minimal'
};
---

<Timeline data={myEvents} config={config} />

Custom Location Configuration

---
import Timeline from '@jaydixit/transitpaths/src/components/Timeline.astro';
import type { LocationConfig } from '@jaydixit/transitpaths';

const customLocations: LocationConfig = {
  tokyo: {
    name: 'Tokyo',
    theme: 'japan',
    emoji: '🗼',
    icon: '⛩️',
    iconName: 'tabler:torii',
    keywords: ['tokyo', 'japan'],
    title: 'Tokyo',
    country: 'Japan'
  },
  kyoto: {
    name: 'Kyoto',
    theme: 'japan',
    emoji: '🏯',
    icon: '⛩️',
    iconName: 'tabler:temple',
    keywords: ['kyoto'],
    title: 'Kyoto',
    country: 'Japan'
  }
};

const config = {
  locations: customLocations
};
---

<Timeline mdxContent={content} config={config} />

Programmatic Parsing

import { parseItinerary, buildChronoEvents } from '@jaydixit/transitpaths';

// Parse MDX content
const { timelineData, metadata } = parseItinerary(mdxContent, {
  locationConfig: myLocations,
  smartQuotes: customSmartQuotesFunction
});

// Build chronological events
const events = buildChronoEvents(timelineData, myLocations);

// Use events in your application
console.log(events);

Configuration Options

TimelineConfig

interface TimelineConfig {
  // Custom location definitions
  locations?: LocationConfig;
  
  // Date formatting (future feature)
  dateFormat?: string;
  
  // Visual theme
  theme?: 'default' | 'minimal' | 'compact' | string;
  
  // Feature toggles
  features?: {
    calendar?: boolean;        // Show calendar navigation
    currentLocation?: boolean;  // Show current location box
    navigation?: boolean;       // Show navigation buttons
    todoItems?: boolean;       // Show todo checkboxes
    autoScrollToToday?: boolean; // Auto-scroll to current date
  };
  
  // Custom functions
  smartQuotes?: (text: string) => string;
  customIconResolver?: (cityName: string) => string;
}

Location Configuration

interface LocationDetail {
  name: string;          // Display name
  theme: string;         // Theme key
  emoji: string;         // Location emoji
  icon: string;          // Icon character
  iconName?: string;     // Icon library name (e.g., 'tabler:building')
  keywords: string[];    // Keywords for detection
  title: string;         // Section title
  country: string;       // Country name
  region?: string;       // State/Province (for US/Canada)
}

Styling

Using Built-in Themes

<Timeline mdxContent={content} config={{ theme: 'minimal' }} />

Available themes:

• default: Full-featured with colors
• minimal: Grayscale, reduced visual elements
• compact: Smaller spacing for dense timelines

Custom CSS

Override CSS variables for custom styling:

.transitpaths-timeline {
  --timeline-primary: #3b82f6;
  --timeline-secondary: #fb923c;
  --timeline-background: #ffffff;
  --timeline-text: #1f2937;
  --timeline-border: #e5e7eb;
}

Transit Event Syntax

The parser recognizes several transit patterns:

## August 15
- fly New York ➔ London
- train London → Paris
- drive Paris -> Lyon
- car Lyon ➔ Nice
- road trip Nice ➔ Monaco

Supported transit modes:

• fly: Airplane (✈️)
• train: Train (🚆)
• drive, car, road trip: Car (🚗)

Todo Item Syntax

## August 20
- [ ] Book hotel
- [ ] Reserve restaurant
- [x] Buy tickets
- Regular activity (no checkbox)

API Reference

Functions

parseItinerary(mdxContent, config)

Parses MDX content into structured timeline data.

Parameters:

• mdxContent: String containing MDX content
• config: ParserConfig object

Returns: { timelineData, metadata }

buildChronoEvents(timelineData, locationConfig)

Builds chronologically ordered events from timeline data.

Parameters:

• timelineData: Array of TimelineEntry objects
• locationConfig: Location configuration object

Returns: Array of ChronoEvent objects

getCityLocation(cityName, locationConfig)

Gets location information for a city.

Parameters:

• cityName: Name of the city
• locationConfig: Location configuration object

Returns: Location string or null

Examples

Travel Blog

---
import Timeline from '@jaydixit/transitpaths/src/components/Timeline.astro';
import { getEntry } from 'astro:content';

const trip = await getEntry('trips', 'europe-2025');
---

<article>
  <h1>{trip.data.title}</h1>
  <Timeline mdxContent={trip.body} config={{
    theme: 'default',
    features: { 
      currentLocation: true,
      autoScrollToToday: true 
    }
  }} />
</article>

Conference Schedule

---
import Timeline from '@jaydixit/transitpaths/src/components/Timeline.astro';

const conferenceSchedule = `
# Tech Conference 2025

## March 15
- fly San Francisco ➔ Austin
- [ ] Check in to hotel

## March 16
- Keynote: Future of AI
- Workshop: Building with LLMs
- [ ] Networking dinner

## March 17
- Panel: Ethics in Technology
- fly Austin ➔ San Francisco
`;

---

<Timeline mdxContent={conferenceSchedule} config={{
  theme: 'compact'
}} />

Browser Support

• Modern browsers (Chrome, Firefox, Safari, Edge)
• ES2022+ JavaScript features required
• CSS Grid and Flexbox support required

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Author

Jay Dixit

Changelog

1.0.0

• Initial release
• MDX parsing support
• Timeline component
• Location tracking
• Todo items
• Multiple themes