project · static site · data pipeline
Chronological History — 4.54 billion years on one axis
An interactive timeline from the formation of the Earth to this year, built to make historical simultaneity visible. Ask it about 1555 and it will tell you that the Mughal Empire was in year 29 of 331 and that Akbar was 13 — which is the part a bar cannot draw.
What it actually shows
You land on a chart. Time runs left to right along the top — 4.54 billion years ago at one end, this year at the other — and under it sit thirteen horizontal lanes, one per region: Earth & Life, the Indian Subcontinent, East & Southeast Asia, Central Asia & the Steppe, West Asia & Persia, Europe & Mediterranean, Africa, the Americas, Oceania, then Science, Philosophy, Art & Culture, and a Global lane for things that belong to nowhere in particular.
Each of the 522 entries is a bar covering the years it spans, or a small diamond if it happened in one. So reading down a column tells you what was going on everywhere at once, and reading along a lane tells you what followed what. That is the whole idea: you can look up the Mughal Empire and get 1526–1857, look up Akbar and get 1542–1605, and still have no feel for the fact that they are one story at two magnifications — or that while Akbar was holding public debates between rival faiths, Europe was in the middle of its wars of religion.
Moving around
Drag to pan, scroll or pinch to zoom. Seven buttons jump to a named stretch — Hadean, Mesozoic, Ice Age, Bronze Age, Classical, Medieval, Modern — so no part of 4.54 billion years is more than one click away from any other. There are From and To fields that take 4.54 Ga, 66 Ma, 12 ka, 500 BCE and 1526 equally, each with a dropdown of boundaries nobody would think to type — "2.58 Ma, Pleistocene begins" is only obvious if you already knew it. A minimap along the bottom shows where in the whole range you are sitting, and can be dragged to set the window directly. / focuses the search box.
Two behaviours are worth knowing because they are not obvious from looking. Clicking a lane's name collapses it into a single thin band, so you can flatten the regions you are not reading. And once the window narrows to under two thousand years, the Indian Subcontinent lane splits into North, South, East and West India, the Deccan, Himalaya & Tibet, and Sri Lanka — only that one lane, because expanding all thirteen would leave you with about thirty-five rows.
Clicking something
Click a bar and a card opens — a drawer from the right on a desktop, a sheet from the bottom on a phone: what kind of thing it is, its dates, a picture with its Wikimedia credit and licence, a summary, and why it matters. If the dating is soft the card says so in its own words — "Dates are approximate", or "Scholars disagree about these dates" — and an On the dating note explains the dispute where there is one.
Then two lists that deliberately answer different questions. In this lane is a small strip of the entry's own region showing what came before it, beside it and after it, with Earlier and Later buttons to walk along. At the same time looks outward instead — the rest of the world, meanwhile. Below those: related entries, links to read the text itself where one exists, the sources behind the dating, and a Wikidata id. While a card is open the rest of the timeline dims to what overlaps it, so the answer is visible on the chart and not only in the list.
Cutting the whole thing at one year
The second view is the one that justifies the project. Click the axis, put the same year in both date fields, or go straight to #/year/1555, and instead of a chart you get a cross-section: every entry underway in that year, grouped by region, each annotated with how far into its own span it had got. Steppers move you a year, a decade or a century either way, and one link puts you back on the timeline at the same spot. That view gets a section of its own below, because its interesting parts are all refusals to overstate.
Underneath
522 entries written by hand as YAML, compiled by a small Python pipeline into JSON that GitHub Pages serves as plain files. No backend, no database, no framework, and no build step in the browser — about 3,800 lines of vanilla ES modules drawing onto a canvas. Nothing to install and nothing to run; the deployed site is files on a CDN.
The axis: why a logarithm is the wrong answer
Compressing 4.54 billion years onto one bar obviously needs a logarithm somewhere. The obvious version is wrong. A plain log of years-before-present compresses the wrong end: it hands the Pleistocene about a third of the axis and leaves the whole of recorded history with a twelfth. The result is arithmetically honest and useless for the thing people actually came to look at.
So the scale is anchored. Eleven [year, position] pairs decide how much of the bar each stretch of time is allowed to have, which makes the allocation an editorial decision rather than a side effect:
export const ANCHORS = [
[ORIGIN_YEAR, 0.0], // -4.54 Ga
[-541_000_000, 0.1], // Cambrian
[-66_000_000, 0.2], // the asteroid
[-2_580_000, 0.3], // Pleistocene
[-11_700, 0.42], // Holocene <-- deep time ends with 42%
[-3_000, 0.52], // writing
[-500, 0.62],
[500, 0.72],
[1_500, 0.84],
[1_800, 0.92],
[PRESENT, 1.0], // tracks the current year
];
Deep time keeps roughly 42% of the axis; everything since 3000 BCE gets 48%. Within a segment the interpolation is linear in log-years-before-present, so the curve stays smooth and strictly monotonic end to end — an axis that folded back on itself anywhere would let two different years land on the same pixel. The last anchor tracks new Date().getFullYear(), so the scale does not quietly stop short as years pass.
The part that needed a second attempt is zooming. A window projects through unit space — the anchored [0, 1] position — and not through the raw logarithm. Projecting through the log directly is simpler, and it silently bypasses the anchors: recorded history collapses straight back to its twelfth, and the whole module stops meaning anything. Inside a single anchor segment unit is linear in log-years anyway, so a zoomed window is still near-linear in years, which is what you want once you are looking at three centuries rather than three eons.
There is no year zero
This is the single most error-prone thing in the codebase, so it gets exactly one conversion boundary. Historical numbering has -1 = 1 BCE and 1 = 1 CE, with nothing in between. Astronomical numbering has 0 = 1 BCE, and arithmetic simply works.
Source files and display strings use historical numbering. Every calculation — durations, ages, interval overlap, tick spacing — routes through astro() first, and astro(0) raises. pipeline/model.py and site/js/format.js are deliberate mirrors of each other, down to the docstrings, because the pipeline and the browser both do year arithmetic and a disagreement between them would be invisible in the output.
That one rule is worth the three bugs it prevents, all of which I hit in the axis:
- Elapsed, not inclusive.
duration(1526, 1857)is 331. Subtracting raw historical years across the seam counts a year that never existed, so a window straddling it reads one year wider than it is — and the one-year zoom floor then stops a full year early. - Measure spacing in one numbering, snap in the other. Measuring tick spacing historically inflates any gap that straddles the boundary, leaving a ragged ladder on every window spanning BCE to CE. Snapping astronomically instead is no better: astro
-80formats as "81 BCE". So spacing is measured astronomically and snapping happens in historical years, on purpose. - A tick that lands on year 0 is dropped, not nudged. Moving it to year 1 would collide with the neighbouring tick, which is a worse failure than a missing label.
And then the deliberate exception, which is the bit I like. astro() rejects year zero because no entry may claim it — that is a data error and it should be loud. But a view's edge, a drag midpoint and an interpolated tick are continuous quantities that have to pass smoothly through the seam, so timescale.js imports unguarded conversions for exactly those and says why at the import site. Two different jobs, two functions, rather than one function with a flag.
Ticks that stay round at every zoom level
Axis labels are sampled evenly on screen and then snapped to round years, rather than the other way round. On a scale this compressed, evenly spaced round years pile up at one end of the window.
Snapping then splits by regime, and both halves were learned the hard way. In deep time the step is capped at half the sample's own magnitude, because a sample at 430 Ma whose neighbours are a billion years away otherwise rounds to zero and every label piles onto the present. Inside recorded history there is no such cap — capping by |year| gives a sample near the seam a finer step than its neighbours, which is exactly what made BCE-to-CE windows come out ragged.
When every sample agrees on a step the window is effectively uniform, and the ticks are laid out on that step directly. If that yields too many, the code climbs the 1/2/5 ladder until the count fits rather than falling back to per-sample snapping — which rounds an even 4.4-year spacing onto alternating 4s and 6s. Thinning happens last, in pixels, because a coarser sampling does not give you fewer good ticks; it gives you bad ones.
The year slice — what a bar cannot draw
Here is what #/year/1555 actually returns — real output, 52 entries deep, abridged:
Earth & Life
Himalayan Orogeny -58998051 – 2026 59 million years in
Homo sapiens -313051 – 2026 314,605 years in
Indian Subcontinent
Tulsidas 1497 – 1623 age 23–58
Mughal Empire 1526 – 1857 year 29 of 331
Akbar 1542 – 1605 age 13
Vijayanagara Empire 1336 – 1646 year 219 of 310
Mirabai 1498 – 1557 age 51–57
East & Southeast Asia
Ming Dynasty 1368 – 1644 year 187 of 276
Sengoku period 1467 – 1615 year 88 of 148
Europe & Mediterranean
The Reformation 1517 – 1648 year 38 of 131
Art & Culture
Michelangelo 1475 – 1564 age 80
Miguel de Cervantes 1547 – 1616 age 8
Global
Malaria -8051 – 2026 9605 years in
Tuberculosis -7051 – 2026 year 8605 of 9076
Three decisions are visible in that block, and each of them is a refusal to overstate.
Past ten thousand years, it stops counting. Tuberculosis spans 9,076 years and gets "year 8,605 of 9,076". Malaria spans 10,076 and gets "9,605 years in". The Himalayan orogeny gets "59 million years in", because "year 58999605 of 59000076" is true and useless — that line is in the source, and it is the right instinct.
A bracketed birth becomes a range of ages, never the flattering end. Tulsidas's birth is bracketed 1497–1532 in the dataset, so 1555 gives "age 23–58" rather than picking one. And when the queried year falls inside the bracket, the person may not have been born yet and the lower bound goes negative: "age −20–63" is not an age, so it reports "age up to 63", which is what is actually known.
Anything that begins or ends in the queried year sorts first, because a year in which something started is more interesting than a century merely passing through it.
What counts as "at the same time"
Each entry's card lists what else was going on. The first version listed everything that overlapped, which sounds correct and reads as noise, because the dataset contains background: the Holocene, Homo sapiens, and a Himalayan orogeny that runs from 59 Ma to the present and therefore overlaps almost every entry in the file. They appeared under everything, were dimmed by nothing, and left the ghosted timeline looking barely shadowed.
So a neighbour may run at most 12× the subject's own span and still count as happening at the same time — with a floor of 1,000 years, which is the half that keeps the opposite case working. A one-year battle inside a four-century dynasty should still show the dynasty; that is its context, not its wallpaper.
Akbar's card was missing Akbar
My favourite bug in the repo. Each card carries a small strip of its own lane — what came before this entry, beside it and after it — and the strip reuses the main chart's row packer rather than reimplementing it.
Handing that packer [entry, ...neighbours] privileges the entry not at all: the packer sorts by position before it packs. Where a card's neighbours all overlap each other, every one of them takes a row of its own, and with four rows available and nine overlapping bars, the card's own entry could land in the overflow and vanish from its own strip. Akbar's card did exactly that — surrounded by Vijayanagara, Surdas, Tulsidas, Mirabai and the Kabir collections, the one entry the card was about was the one missing from it.
The fix is to reserve a row rather than join the queue: pack the entry alone into one row, then pack the neighbours into what is left. It also gives every card a fixed shape — you are the top line, everyone else is below — instead of a position that moves from card to card.
Packing in pixels, and counting what does not fit
Row packing happens in pixel space, not year space. On a logarithmic axis "four years apart" means something entirely different at 66 Ma than at 1555, whereas "four pixels apart" is what actually decides whether two bars read as separate — at any zoom level.
First-fit interval packing, six rows maximum, and one invariant carries the honesty: rows.flat().length + hidden always equals the number of entries in view. Overflow is counted, never discarded, so the "+N more" the renderer draws is a number you can trust. The same instinct appears one function down — an entry whose lane is missing from the taxonomy falls through to global rather than disappearing, because a missing lane is a data bug and a silently dropped entry hides it. Hit testing pads each target by 10px so a 3px bar stays clickable, but ties are broken against the drawn edges, so the padding never decides which bar you meant.
Two payload shapes, for two access patterns
The client answers search, the year slice and visible-window culling from one file. All three are interval queries over the whole dataset, so none of them can afford a round trip — which forces that file to be complete, which in turn forces it to be small.
So spine.json is an array-of-arrays with a field list: 13 columns, one row per entry, aliases pipe-joined into a single string so the row stays flat, and flags packed into an integer. All 522 entries come to 58 KB. Everything a reader only sees after clicking — summaries, significance, notes, sources, images and their licences — lives in era bundles totalling 342 KB across 20 files, fetched lazily and cached, with failures deliberately not cached.
The bundles are bucketed by era rather than hashed, because reads are temporally local: a year slice or a zoomed window touches a handful of adjacent eras, not every shard. And the bucket boundaries follow entry density rather than elapsed time — the Mesozoic is one bucket covering 186 million years, while 1500 CE onward gets a bucket per century. The century ladder is extended one century past the present, so an ongoing entry whose end bound tracks the current year always has a bucket to live in.
The data is the risky part, and the repo says so
This is the section I would want to read first in someone else's project of this shape, and it is the one most timelines skip. The statement is at the top of pipeline/citations.py:
So nothing is asserted. The citation pass fetches each article, follows redirects to the canonical title, and looks for the entry's own dates in the article's opening section. Entries whose dates the article does not mention are reported rather than hidden, because those are exactly the ones worth a human's attention. Deep-time entries are recorded as unchecked rather than failed, since no article prints 2.1 Ga as a bare number. And the module is explicit about what it has actually established: these are tertiary sources, they point a reader at where a dispute is documented, and they are not evidence that the bracket in this dataset is right.
Images draw the same line, and it is the cleanest expression of the principle in the repo. Which picture suits an entry is an editorial judgement, so the entry-to-file mapping is curated by hand. What that file's licence is is a matter of fact, so it is fetched from the Commons API rather than assumed — an image whose terms you guessed at is one you are publishing unlawfully. license and source are required fields, not optional ones; credit and licence are displayed with every picture because most are CC BY-SA and that is a condition of use; and the URL validator refuses anything that is neither https nor a path under images/, with no traversal and no absolute paths, so a manifest can never point the page outside its own image directory.
The loader is strict in the same spirit — an unknown field is an error naming the file and the entry, a duplicate id is an error rather than a silent overwrite, and a required field that is present but blank is an error too. Without that last check a bare title: becomes the literal string "None" and rides all the way through to the rendered timeline. A typo that is silently ignored produces a timeline that is quietly wrong rather than obviously broken.
And where a religious tradition holds a text to be contemporaneous or eternal, the entry's note says so plainly rather than presenting the academic dating as settled. It is a reference tool, not an argument.
498 tests, none of which need a browser
The geometry is pure, and that is the entire test strategy. timescale.js, layout.js, slice.js, context.js, wrap.js, search.js, router.js, format.js and title.js take no DOM, no fetch and no storage; timeline.js draws on a canvas, handles input and owns nothing else. wrap.js is handed a measuring function rather than a canvas, so text layout is testable without a font.
$ node --test site/js/
# tests 296
# suites 52
# pass 296
# fail 0
$ pytest -q
........................................................................ [ 35%]
........................................................................ [ 71%]
.......................................................... [100%]
202 passed
One of those files is really a test of judgement rather than of code. test_date_agreement.py pins down what "our bracket agrees with Wikidata" is allowed to mean: a point inside the bracket agrees, a point on the edge agrees, and outside it the tolerance is exactly one year anywhere inside recorded history — so 1858 corroborates a 1526–1857 bracket and 2150 does not. The tolerance then scales for deep time, one percent of the magnitude, because one year is the right slack for 1526 and meaningless at 3.9 million, where a BP-offset date and a round figure differ by thousands while meaning the same thing. Crucially, no Wikidata dates at all is not agreement — the alternative is a silent pass for every entry nobody has data for, which is the most comfortable and least useful outcome available.
A phone is not a narrow desktop
Everything had been sized for a wide screen and then inherited by the phone, where 11px text on a 14px bar reads as fine print. So bars get taller on a phone and type gets larger, and rows no longer shrink to fit the screen — there are more of them than fit, and the chart scrolls.
Below 560px the lane-name column disappears entirely and each lane gets a name strip above it instead. The arithmetic is the argument: a 96px gutter was 26% of a 375px screen, leaving 279px for 4.5 billion years.
Lane names wrap rather than truncate. Truncation was the old behaviour and at phone width every multi-word lane came out as "Centr…", "Ameri…", "Scien…", which names nothing; now only a single word too wide for the column is ever cut, and then only that word. Bar labels got the opposite fix — a bar too narrow for its whole title used to draw nothing at all, so it now shows as much as fits, cut at a separator rather than mid-word. With one exception: if all that fits is "The…", nothing is drawn, because an article alone names nothing and the space is better left empty.
A different name in India
Small thing, and my favourite file in the repo. Opened from an Indian timezone or an en-IN locale, the site calls itself Aap chronology samajhiye rather than Chronological History.
What makes it worth mentioning is how it decides. title.js is pure — it is handed the environment rather than reading it, so the decision is testable without a browser and without pretending to be in Mumbai. There is no geolocation and no IP lookup; the only signals are the two the browser already volunteers, the machine's timezone and the reader's chosen locales, so nothing about the reader leaves the page. Asia/Calcutta counts as well as Asia/Kolkata, because some systems still report the older name for the same zone. And a bare language subtag does not count: hi says Hindi, not India. The region subtag is never the first one, which matters more than it sounds — in on its own is the deprecated code for Indonesian, and reading it as India would put a Hindi pun in front of readers in Jakarta.
What is not built
docs/deep-time-animation.md is a feasibility answer with no code behind it: a procedurally drawn, risograph-styled view of the Earth at whatever moment the timeline is sitting on, scrubbed by the cursor rather than played. Its conclusion is that the hard parts are not the ones people expect. Animation performance is a non-issue. The three that actually decide it are span — plate reconstructions are credible back to roughly 600 Ma, so for about 87% of this timeline there is no map to draw; licensing — every image on the site carries a resolved Commons licence, and the famous palaeogeographic maps mostly do not permit reuse; and taste — a scene that says "it rained for millennia" asserts something the evidence supports only loosely, and an animation makes that kind of smoothing very easy.
There is also a selection criterion in there I enjoyed: pick scenes whose content is repetition, because that is what looks rich for very little code. Ice, forest, falling rain and Cambrian body plans repeat well. Dinosaurs repeat badly — a dinosaur is a one-off silhouette rather than a pattern, and it is the scene most likely to look amateur.
The Wikidata importer works and data/imported/ exists, but the built counts are curated: 522, imported: 0. Breadth via SPARQL is planned, with curated entries always winning on merge. Coverage today is deliberately deep on the Indian subcontinent — Vedic period, scriptural composition, Bhakti-era saints, the dynasties, the Mughals — with enough world context that any year you pick shows meaningful parallels.
It is live at shivam1410.github.io/chronological-history (opens in new tab). Try 1555, or 1947, or drag the axis back past the asteroid.