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
- What kinds of historical-geography questions Jiangshan Chronicles can answer
- How the timeline, point-to-place tracing, point-to-person tracing, and point-to-event tracing interactions work
- How to run it locally or deploy with Docker
- How to let AI query it via MCP, Skill, and URL protocols
- Its data sources and licensing, especially which data is not covered by GPL
Prerequisites
- A basic interest in Chinese history is enough
- Local running requires knowledge of Python's
http.server, or Docker - Optional: familiarity with MCP and Agent Skills
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
- ⭐ GitHub Stars: approximately 7,301
- 🍴 Forks: approximately 875
- 💻 Language: JavaScript
- 📅 Created: 2026-07-23, last push 2026-11-16, still actively updated
- 📄 License: GPL-3.0 (only for code and self-drawn data, see "Data Sources and Licensing" below)
- 👤 Author: DeanChensj
- 🌐 Online: deanchen.me/jiangshan-map
- 🌏 README available in Simplified Chinese, Traditional Chinese, Japanese, and English
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:
- Check data sources before commercial use or redistribution: code being GPL-3.0 does not mean all data inside can be freely used for commercial purposes
- When exporting GeoJSON, prefecture boundaries are not exported by default; you need to add
--with-prefecturesto export them, an intentional protection by the project - GeoJSON export range is 403 BC to 1948, excluding modern province boundaries
- When reusing, you should credit "Jiangshan Atlas" and the original repo link; the citation format for CHGIS is CHGIS, Version: 6. © Fairbank Center …, 2016.
Accuracy: What It Says Itself
This is the most commonly questioned aspect of historical maps. The README is explicit:
- Historical territories and administrative boundaries are illustrative approximations, not surveying results, and should not be used as authoritative boundary references
- The original sources for early first-level administrative divisions are not recorded
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
index.html,css/,js/: frontend coredata/: atlas data, divided intoatlasandsourcesgeojson/: GeoJSON examples and localization scriptstopics/: special topic pagesscripts/: build, validation, export, and MCP Serverskills/: Agent Skillworkers/: contains astatsdirectory; I haven't read it, not sure of its purpose (if you care about privacy, you can check it yourself)Dockerfile,docker-compose.yml: containerized deployment
Limitations and Notes
- Boundaries are illustrative: The README explicitly states they cannot be used as authoritative references
- Some data has usage restrictions: Prefecture boundaries are academic non-commercial only and cannot be redistributed
- Limited export range: GeoJSON only goes up to 1948, excluding modern province boundaries
- Limited embedding platforms: WeChat Official Accounts, Zhihu, and Xiaohongshu do not support embedding
- Docker image must be built yourself: Not published to a registry
- Young project: Created in July 2026, no stable version promise seen; evaluate maturity yourself before using
Project Links and Resources
- 🌟 GitHub: https://github.com/DeanChensj/jiangshan-map
- 🌐 Online: https://deanchen.me/jiangshan-map/
- 🤝 Contributing:
CONTRIBUTING_ZH.mdin the repo; for data corrections, submit an Issue via the template, preferably with sources - 📄 License: Code and self-drawn data under GPL-3.0; prefecture data has additional restrictions
Summary and Outlook
Key Points Recap
- Positioning: A pure static interactive map of Chinese history, about 2,400 years and 18 historical periods, drag the timeline to see changes
- Rich interactions: point-to-place tracing, point-to-person tracing, point-to-event tracing, and multiple person journeys can also mark "shared paths"
- AI-friendly: local MCP Server, Agent Skill,
llms.txt, and URL protocols - Check data licenses: code is GPL-3.0, but prefecture boundaries are academic non-commercial only and cannot be redistributed
- Boundaries are illustrative: suitable for understanding broad trends, not as authoritative verification
Who It's For
- People who want to visually see geographic changes when reading history and poetry
- Creators of history courses and science content who need embeddable interactive maps
- Developers who want to study "how to make a static website AI-friendly" - this combination of MCP, Skill, and
llms.txtis worth referencing
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
Top 1 from juejin.cn, machine-translated. The original thread is authoritative.
Suggestion: add the Xia, Shang, and Western Zhou periods, and including the Three Sovereigns and Five Emperors era would make it even more perfect.