Historical Timeline Skill

Generate interactive historical timelines as self-contained HTML files powered by TimelineJS3.

Critical: Things Claude Won't Know Without This Skill

BCE dates use negative year numbers

{"year": -551, "month": 9, "day": 28}

This renders as "551 BCE". No special syntax — just negative integers. There is no year 0: -1 is 1 BCE and 1 is 1 CE (the builder raises ValueError for year 0). If your source gives astronomical years (where 0 = 1 BCE), subtract 1 from every year ≤ 0 first.

The scale property matters for ancient dates

For timelines spanning thousands of years or BCE dates, set "scale": "human" (the default). Use "scale": "cosmological" only for astronomical/geological timescales.

Headlines and text are HTML

headline, text, caption, and credit accept HTML. TimelineJS3 cleans this HTML with its built-in sanitizer (DOMPurify) before showing it, and the builder escapes the embedded JSON so no field can break out of the page's <script> block. Still, escape plain text that comes from outside data if you do not want it read as markup.

The output is a single standalone HTML file

The Python script generates a complete HTML file that loads TimelineJS3 from CDN. No server, no build step — just open in a browser. The JSON data is embedded inline.

Title slide has no start_date

The title object is a special slide that appears first. It does not use start_date. Only events entries require dates.

display_date overrides rendered dates

If the default date rendering is wrong (e.g., you want "Spring 221 BCE" instead of "221 BCE"), set display_date on the date object or the slide:

{
  "start_date": {"year": -221},
  "display_date": "Spring 221 BCE",
  "text": {"headline": "Qin Unification"}
}

Groups create labeled rows

Events with the same group string are clustered in adjacent rows on the timeline nav, making it easy to show parallel threads (e.g., "Politics", "Culture", "Military").

Eras label background spans

Eras are colored bands behind the timeline that label periods (e.g., "Han Dynasty", "Tang Dynasty"). They require both start_date and end_date.

Workflow

1. Generate timeline JSON

Build a TimelineJS3 JSON object with events. The Python script provides a builder API:

from scripts.timeline_builder import TimelineBuilder

tl = TimelineBuilder(title="The Tang Dynasty", subtitle="618–907 CE")

# Add eras (colored background spans)
tl.add_era(-221, 220, "Imperial China Begins", end_month=12)
tl.add_era(618, 907, "Tang Dynasty")   # era colors are set by TimelineJS3

# Add events
tl.add_event(
    start_year=618, start_month=6, start_day=18,
    headline="Li Yuan founds Tang",
    body="<p>After the collapse of the Sui dynasty...</p>",
    group="Politics",
)
tl.add_event(
    start_year=701, end_year=762,
    headline="Li Bai (李白)",
    body="<p>One of the greatest Chinese poets.</p>",
    group="Culture",
    media_url="https://upload.wikimedia.org/wikipedia/commons/4/4e/Li_Bai.jpg",
    media_caption="Li Bai, the Immortal Poet",
)
tl.add_event(
    start_year=-551, start_month=9, start_day=28,
    end_year=-479,
    headline="Confucius (孔子)",
    body="<p>Philosopher whose teachings shaped Chinese civilization.</p>",
    display_date="551–479 BCE",
)

# Save as standalone HTML
tl.save_html("tang_dynasty.html")

# Or get raw JSON for custom use
import json
print(json.dumps(tl.to_dict(), indent=2, ensure_ascii=False))

2. Open the HTML file

open tang_dynasty.html        # macOS
xdg-open tang_dynasty.html    # Linux
start tang_dynasty.html       # Windows

The timeline is fully interactive: click events, scroll through time, zoom in/out.

3. Customize appearance

Pass options to save_html():

tl.save_html(
    "timeline.html",
    font="Georgia-Helvetica",          # Built-in font pair
    initial_zoom=2,                     # Starting zoom level
    timenav_position="bottom",          # Nav bar position
    hash_bookmark=True,                 # URL updates with slide
    start_at_end=True,                  # Start at last event
    default_bg_color="#1a1a2e",         # Dark background
    language="zh-cn",                   # Chinese interface
)

JSON Format Quick Reference

{
  "title": {
    "text": {"headline": "Timeline Title", "text": "<p>Subtitle or description</p>"},
    "media": {"url": "https://example.com/image.jpg", "caption": "Credit"}
  },
  "events": [
    {
      "start_date": {"year": 618, "month": 6, "day": 18},
      "end_date": {"year": 907},
      "text": {"headline": "Event Title", "text": "<p>Details in HTML</p>"},
      "media": {"url": "...", "caption": "...", "credit": "..."},
      "group": "Category",
      "display_date": "Custom date text",
      "background": {"color": "#2a9d8f"},
      "unique_id": "event-001"
    }
  ],
  "eras": [
    {
      "start_date": {"year": 618},
      "end_date": {"year": 907},
      "text": {"headline": "Tang Dynasty"}
    }
  ],
  "scale": "human"
}

Date object fields

Media types supported

TimelineJS3 auto-detects media type from URL:

• Images (jpg, png, gif, webp)
• YouTube, Vimeo, Dailymotion
• Wikipedia articles
• Google Maps
• Twitter/X posts
• Flickr, Instagram
• Spotify, SoundCloud
• PDF documents
• Any URL (renders as iframe)

Built-in Font Pairs

default, Bitter-Raleway, Dancing-Ledger, Georgia-Helvetica, Lustria-Lato, Medula-Lato, Old-Standard, Playfair-Faunaone, PT, Roboto-Megrim, Ubuntu, UnicaOne-Vollkorn

API Etiquette

• TimelineJS3 loads from unpkg.com, pinned to @knight-lab/timelinejs@3.9.13 with Subresource Integrity (SRI) hashes, so the browser refuses a changed file. To upgrade, change the version and both hashes in timeline_builder.py together.
• If embedding media from external sources (Wikipedia, Wikimedia Commons), follow their usage policies
• Generated HTML files are fully offline-capable after first load (browser caches CDN assets)

Related Skills

• cbdb-api / cbdb-local: Retrieve biographical data for Chinese historical figures to populate timeline events
• chgis-tgaz: Look up historical place names and coordinates for timeline event context
• cjk-calendar: Convert lunisolar dates to Gregorian for accurate timeline placement
• arxiv-search: Find scholarly articles about historical periods for timeline research

Resources

• references/timelinejs_reference.md — Complete TimelineJS3 JSON format, options, and media type documentation
• scripts/timeline_builder.py — Python builder for generating timeline JSON and standalone HTML files

Feedback and Citation

Report a problem. This skill is part of the public repository kltng/humanities-skills. If it fails (an API changed, a script errors, or these instructions are wrong), report it as a GitHub issue:

1. Ask the user before filing. Issues are public.
2. Check for an existing report: gh issue list --repo kltng/humanities-skills --state all --search "historical-timeline"
3. File it: gh issue create --repo kltng/humanities-skills --label bug --title "[historical-timeline] <short summary>" --body "<details>". Without gh, give the user this link: https://github.com/kltng/humanities-skills/issues/new?template=skill-problem.yml
4. Include the skill name and version, what you ran, the error text, what you expected, and the environment (OS, Python version). Leave out API keys, personal data, private file paths, and unpublished research.

Cite. If this skill helped work that is published, please cite it, together with the data source it uses:

Tang, Kwok-leong. humanities-skills: historical-timeline (version <version at the top of this file>). GitHub, <year>. https://github.com/kltng/humanities-skills

When you help a user write up results that relied on this skill, remind them once about this citation.