opensourceprojects.dev

A broadsheet for software that doesn't ask for your email

A 2,400-year interactive atlas of China you can scrub through
GitHub RepoViews12

Project Description

View on GitHub

A 2,400-Year Interactive Atlas of China You Can Scrub Through

You're reading classical Chinese poetry or a dynastic history, and a place name comes up—Jiankang, Huangzhou, Languan Pass—and you have no idea where any of it sits on a modern map. Or maybe you've wondered how many names Chang'an carried over two millennia, or how the borders of the realm actually shifted from one century to the next. Chronicles of the Realm (jiangshan-map) is an attempt to answer those questions in a single interactive atlas you can drag a timeline through.

What It Does

Chronicles of the Realm is an interactive historical atlas of China spanning from the Warring States period (403 BCE) to the present—roughly 2,400 years across 18 historical periods. It's built around a parchment-style map canvas where you scrub a timeline and watch territories rise, fall, and shift. The atlas layers in multi-stage territorial and prefecture snapshots, ancient cities, strategic mountain passes, poetic and battlefield landmarks, chronological milestones, and reigning monarchs with their imperial eras.

The core interaction is simple: drag the timeline, click any city, and you travel through space and time. At major territorial milestones, the map shows multi-stage evolution and dashed boundary diffs so you can see exactly what changed and when. Polities are rendered side-by-side in high-contrast traditional parchment hues—everything from the Seven Warring States to the Three Kingdoms warlords, the Northern and Southern Dynasties, the Five Dynasties and Ten Kingdoms, and the Song, Liao, Western Xia, Dali, Jin, and Mongol realms. Hovering over a polity in the legend highlights its territory; clicking opens a profile with its lifespan, capitals, and a short history.

Why It's Cool

The timeline scrubbing is the whole point. Most historical atlases are static—you flip to a page and that's your snapshot. Here you drag through centuries and watch the map redraw itself. The dashed "ghost boundary diffs" at territorial milestones are a genuinely clever touch: instead of just showing you the new border, they show you what moved.

It treats place names as living things. The atlas is built to answer questions like how many names Chang'an held across two millennia and what happened on that soil. If you've ever tried to trace a city through dynastic renamings, you know how messy that gets. Having it in one place, tied to a timeline, is the kind of thing that saves you an afternoon of cross-referencing.

The scope is unusually wide. Eighteen periods is a lot of ground to cover, and the README lists confrontations from the Seven Warring States alongside Zhou, Yue, Ba-Shu, Zhongshan, and Yiqu, all the way through to Zeng Jize's recovery of Ili in 1881 and the 20th-century shift from the "Begonia Leaf" map to the "Rooster" map. That's a long arc, and keeping it navigable in a single interface is the hard part the project is actually solving.

It's built for curiosity, not just reference. The framing around poetry and battlefields—Su Dongpo composing in exile at Huangzhou, Han Yu halting his horse in the snow at Languan Pass, Yue Fei's northern campaign frontier at Zhuxianzhen—suggests the atlas is meant to be explored, not just consulted. That's a different design goal, and it shows in the click-to-travel interaction.

How to Try It

The fastest way in is the live demo, which has an English UI:

  1. Open the live demo: https://deanchen.me/jiangshan-map/?lang=en
  2. Drag the timeline to scrub through periods
  3. Hover over polities in the bottom-left legend to highlight territories, or click to open a profile
  4. Click any city to see its history and location across time

If you want to dig into the source or run it yourself, the repository is at https://github.com/deanchensj/jiangshan-map. The README is available in English, Simplified Chinese, Traditional Chinese, and Japanese, so you can read the docs in whichever you're most comfortable with. There's also a write-up on the story behind the project (in Chinese) linked from the README if you're curious about how it came together.

Final Thoughts

This is a project for anyone who's ever gotten lost in a place name while reading Chinese history or poetry—students, teachers, history buffs, or developers who like seeing data turned into something you can actually touch. It's not trying to be a scholarly reference work; it's trying to make 2,400 years of territorial change something you can feel by dragging a slider. That's a narrow goal, and it's a good one. If the idea of scrubbing through dynasties on a parchment map sounds like your kind of afternoon, it's worth a click.


Follow @githubprojects for more developer tools and open source projects.

Back to Projects
Project ID: jiangshan-mapLast updated: November 17, 2026 at 06:51 AM