跪拜 Guibai
← Back to the summary

Drag a Timeline Across 2,400 Years of Chinese History on This Static Map

"Where on today's map is this ancient city or battlefield?"

This is the 263rd installment of the "One Open-Source Project a Day" series. Today's project is DeanChensj's Jiangshan Chronicles · Chronicles of the Realm (repo name jiangshan-map).

When reading history or poetry, almost everyone has asked the same kind of question: Where are the places Li Bai passed through on his way out of Shu? Where exactly is the Battle of Red Cliffs today? What were the various names of Chang'an across dynasties? These questions are hard to answer by flipping through textual notes, and a static map can't show "change."

Jiangshan Chronicles turns this into a moving map: drag the timeline and territories, administrative divisions, rivers, the Great Wall, and canals change with the eras; click an ancient city to see its evolution across 18 periods; search a person to see their travels. It is a pure static website, no backend needed. More notably, it provides entry points for AI: a local MCP Server, an Agent Skill, and llms.txt.

This article is compiled from the README and repo directory. I have not deployed or run it, nor have I verified the historical data on the map item by item.

What you will learn

Prerequisites


Project Background

Project Introduction

The README describes it as: a pure static interactive atlas website of Chinese history, covering approximately 2,400 years from 403 BC (the Partition of Jin) to the present, designed to answer common questions when reading history and poetry, such as "Where on the map is such-and-such ancient city or battlefield," "How did territories change step by step," and "What were the various names of Chang'an across dynasties." Online at https://deanchen.me/jiangshan-map/.

Project Data

Regarding scale, the repo's About description reads "18 dynasties, 198 territory snapshots, and genealogies of ancient and modern place names, and classical poetry routes." The README body only explicitly gives 18 historical periods and over 2,400 years, without summary numbers for place names or poems, so this article does not list those numbers.

Main Features

The Problem It Solves

When reading history and poetry:
  Place names in textual notes -> don't know where they are today
  Territorial changes -> a static map can't show the process
  Same city -> different names across dynasties, easy to confuse

Jiangshan Chronicles:
  Drag timeline -> territories, administrative divisions, water systems change with era
  Click an ancient city -> see its evolution across dynasties
  Search a person -> see their travels

Core Capabilities

Feature Description
Timeline Draggable and zoomable (drag the handles inward to zoom into short dynasties, double-click to reset); shows the reigning emperor and era name; spacebar to auto-play, left/right keys to jump stages (add Shift for 10-year jumps), supports voice narration
Multiple polities on screen and staged territories Presents polities with high-contrast rice-paper colors, hover legend to highlight, click to open polity archives; when switching stages, a vermillion dashed afterimage of the previous stage is shown
Legend and administrative divisions "Modern province boundaries" and "Modern province names" can be compared with ancient ones; hover over prefectures to check evolution; Yellow River course changes, ancient lake expansions/contractions, Great Wall, canals, Silk Road, Zheng He's route, and ancient coastline change with era
Point-to-place tracing Click an ancient city or famous pass (or double-click the map) to see a famous city inscription, evolution across 18 periods, and fixed-point major events; "Historical Event Summary" can filter dynasties with events, click an event to "time-travel" to that year
Point-to-person tracing Search a person, view their journey stop by stop with synchronized year, emperor, and territory; built-in Qin Shi Huang, Zhang Qian, Zhuge Liang, Xuanzang, Li Bai, Su Shi, Wang Yangming, etc.; supports viewing multiple people together (e.g., Li Bai Du Fu Gao Shi), with "shared path" intersection points marked
Point-to-event tracing Chu-Han Contention, An Lushan Rebellion, Jingkang Incident; each event has 10 nodes in three acts
Easter egg "Atlas Addressing · Ancient Place Name Quiz," 10 questions, with ranks like "Grand Historian · Atlas Master" awarded by score

There's also a topics/ directory containing standalone special pages, such as the Battles of Red Cliffs, Changping, and Feishui, as well as travels of Li Bai, Su Shi, Wang Yangming, Xuanzang, and dynasty pages.

Quick Start

Local Run (it's a static site, any static server works):

git clone https://github.com/DeanChensj/jiangshan-map.git
cd jiangshan-map
python3 -m http.server 8000

Then open http://localhost:8000.

Docker Deployment:

docker compose up -d --build

Access http://localhost:8008. The README notes the image is based on nginx:alpine and is not published to a registry; you must build it yourself.

Embedding in Other Pages: Add &embed=1 to the link and put it in an iframe; you can combine from and to to limit the timeline range, lock=1 to lock it, and autoplay=1 for auto-play. The README notes that WeChat Official Accounts, Zhihu, and Xiaohongshu do not support embedding.

Detailed Analysis

Three AI Entry Points

This is what I find most interesting about this project: it's not just for humans, it also specifically provides interfaces for AI.

1. MCP Server: scripts/mcp_server.js, the README claims zero third-party dependencies, provides three tools:

Tool Purpose
inspect_place Query a place
inspect_person Query a person
search_atlas Search in the atlas

2. Agent Skill: skills/jiangshan-atlas/SKILL.md, includes a command-line script skills/jiangshan-atlas/scripts/jiangshan.py, which can generate maps with --year, --place, --out parameters.

3. llms.txt and URL protocol: llms.txt is a machine-readable description; the URL protocol supports a single point, multiple points in the same year, and multi-year multi-point (years and places correspond in order). The browser side also has window.atlasAPI (locate, inspect, resolvePlace, openPerson, search) and WebMCP.

These three paths correspond to three usage modes: let an Agent call the tools directly; let an Agent generate a map for a specified year and place; or let an Agent compose a URL and send it to you, so you can click and see the located map. I have not actually tested the calling effects; the above is compiled from the README and directory.

Data Sources and Licensing: Please Read This Section Carefully

The project's license is GPL-3.0, but not all data is covered by GPL. The README states:

Data Source License
Code and self-drawn data Project itself GPL-3.0
Polity outlines Manually redrawn starting from aourednik/historical-basemaps Self-drawn parts under GPL-3.0
Prefecture, state, and fu boundaries From CHGIS V6 and Hartwell GIS Not covered by GPL, academic and non-commercial use only, no redistribution
Modern province boundaries DataV GeoAtlas See its source
Rivers and lakes Public domain
Terrain Based on AWS Terrain Tiles (SRTM, GMTED2010, ETOPO1) See its source

Practical implications:

Accuracy: What It Says Itself

This is the most commonly questioned aspect of historical maps. The README is explicit:

In other words, it is suitable for understanding the broad trends of change and the evolution of places, but not for serious boundary verification, and certainly not as a basis for disputed issues.

Under scripts/, there are a number of audit and validation scripts, such as validate_atlas.js, audit_sources.js, audit_topology.js, check_sources.js, indicating the author is doing data checks. But I have not read or run these scripts to see what they check and what the pass rates are.

Repository Structure

Limitations and Notes

  1. Boundaries are illustrative: The README explicitly states they cannot be used as authoritative references
  2. Some data has usage restrictions: Prefecture boundaries are academic non-commercial only and cannot be redistributed
  3. Limited export range: GeoJSON only goes up to 1948, excluding modern province boundaries
  4. Limited embedding platforms: WeChat Official Accounts, Zhihu, and Xiaohongshu do not support embedding
  5. Docker image must be built yourself: Not published to a registry
  6. Young project: Created in July 2026, no stable version promise seen; evaluate maturity yourself before using

Project Links and Resources

Summary and Outlook

Key Points Recap

  1. Positioning: A pure static interactive map of Chinese history, about 2,400 years and 18 historical periods, drag the timeline to see changes
  2. Rich interactions: point-to-place tracing, point-to-person tracing, point-to-event tracing, and multiple person journeys can also mark "shared paths"
  3. AI-friendly: local MCP Server, Agent Skill, llms.txt, and URL protocols
  4. Check data licenses: code is GPL-3.0, but prefecture boundaries are academic non-commercial only and cannot be redistributed
  5. Boundaries are illustrative: suitable for understanding broad trends, not as authoritative verification

Who It's For

Learning Suggestions

First open it online and try a few entry points: drag through the timeline, click a familiar ancient city, then search "Li Bai Du Fu" to see the shared-path markers. For technical details, read scripts/mcp_server.js and skills/jiangshan-atlas/SKILL.md, which show how to turn a website into a tool that AI can call. If you plan to use it commercially or redistribute, read the Data Sources and Licensing section of the README first.


Welcome to PrimeSkills - a carefully curated marketplace for AI Agents and skills, all verified through real enterprise workflows. No gimmicks, only what actually works.

For more practical knowledge and interesting products, visit my personal homepage

Comments

Top 1 from juejin.cn, machine-translated. The original thread is authoritative.

season_zhu

Suggestion: add the Xia, Shang, and Western Zhou periods, and including the Three Sovereigns and Five Emperors era would make it even more perfect.