Introduction
"Where is this ancient city or battlefield on today's map?"
This is the 263rd article in the "One Open Source Project a Day" series. Today's project is DeanChensj's Jiangshan Atlas · Chronicles of the Realm (repo name jiangshan-map).
Reading history or poetry, almost everyone asks the same kind of question: the places Li Bai passed on his way out of Sichuan, where are they now? Where exactly was the Battle of Chibi in today's terms? What was Chang'an called in each era? Looking these up in text footnotes is slow, and a single static map cannot show change.
Jiangshan Atlas makes it a moving map: drag the timeline and territories, administrative regions, rivers, the Great Wall, and canals change with the era; click an ancient city to see its history across 18 periods; search a person to follow their route. It is a purely static site with no backend. What stands out is that it also provides entry points for AI: a local MCP server, an Agent Skill, and llms.txt.
This article follows the README and the repo's directory listing. I did not deploy or run it, and I did not check the historical data on the map for accuracy.
What You Will Learn
- What kinds of historical-geography questions Jiangshan Atlas can answer
- How the timeline and the "click a place, click a person, click an event" interactions work
- How to run it locally or deploy with Docker
- How to let AI query it through MCP, a Skill, and the URL protocol
- Where its data comes from and how it is licensed, especially which data is not under the GPL
Prerequisites
- An interest in Chinese history is enough
- Running locally takes Python's
http.serveror Docker - Optional: some knowledge of MCP and Agent Skills
Project Background
What It Is
The README's positioning: a purely static, interactive historical map of China, covering about 2,400 years from 403 BCE (the partition of Jin) to today, aimed at questions that come up while reading history and poetry, such as "where is this ancient city or battlefield today," "how did the territory change step by step," and "what was Chang'an called through the ages." The live site is https://deanchen.me/jiangshan-map/.
Project Stats
- ⭐ GitHub Stars: about 7,301
- 🍴 Forks: about 875
- 💻 Language: JavaScript
- 📅 Created: 2026-07-23; last pushed 2026-11-16; actively updated
- 📄 License: GPL-3.0 (for code and self-drawn data only; see "Data Sources and Licensing" below)
- 👤 Author: DeanChensj
- 🌐 Live site: deanchen.me/jiangshan-map
- 🌏 READMEs in Simplified Chinese, Traditional Chinese, Japanese, and English
On scale, the repo's About text says "18 dynasties, 198 territory snapshots, plus ancient-to-modern place genealogy and classical poetry routes." The README body states only 18 historical periods and 2,400-plus years, and gives no totals for places or poems, so this article does not give those numbers.
What It Does
The Problem It Solves
When reading history or poetry:
Place names in footnotes → no idea where they are today
Territorial change → a static map hides the process
One city → different names in different eras, easy to mix up
Jiangshan Atlas:
Drag the timeline → territories, regions, and waterways change by era
Click an ancient city → see its history through the ages
Search a person → follow their routeCore Capabilities
| Feature | Description |
|---|---|
| Timeline | Draggable and zoomable (drag the two end handles inward to enlarge short dynasties, double-click to reset); shows the reigning emperor and era name for the year; space bar autoplays, arrow keys jump between stages (Shift jumps 10 years), with voice narration |
| Multiple polities and staged territories | High-contrast rice-paper coloring for polities, legend hover highlights, click to open a polity's file; switching stages shows a vermilion dashed afterimage of the previous stage |
| Legend and regions | "Modern provinces" and "modern province names" for comparing past and present; hover prefectures for their history; Yellow River course changes, ancient lakes, the Great Wall, canals, the Silk Road, Zheng He's voyages, and ancient coastlines change with the era |
| Click a place | Click an ancient city or pass (or double-click the map) for a city note, its history across 18 periods, and events tied to that place; the "Events" panel filters dynasties that have events, and clicking one "travels" to that year |
| Click a person | Search a person to see their route stop by stop, synchronized with year, emperor, and map; includes Qin Shi Huang, Zhang Qian, Zhuge Liang, Xuanzang, Li Bai, Su Shi, Wang Yangming, and more; multiple people at once (such as 李白 杜甫 高适), with shared stretches marked as "traveled together" |
| Click an event | The Chu-Han Contention, the An Lushan Rebellion, and the Jingkang Incident, 10 nodes each, in three acts |
| Easter egg | "Map Quiz of Ancient Place Names," 10 questions, with official ranks such as "Grand Historian · Master of Maps" based on score |
The repo also has a topics/ directory of standalone topic pages, for example battles such as Chibi, Changping, and Feishui, the journeys of Li Bai, Su Shi, Wang Yangming, and Xuanzang, and pages for individual dynasties.
Quick Start
Run locally (it is a static site, so any static server works):
git clone https://github.com/DeanChensj/jiangshan-map.git
cd jiangshan-map
python3 -m http.server 8000Then open http://localhost:8000.
Deploy with Docker:
docker compose up -d --buildVisit http://localhost:8008. The README notes that the image is based on nginx:alpine and is not published to a registry, so you have to build it yourself.
Embed in another page: add &embed=1 to the link and place it in an iframe; combine with from and to to limit the timeline range, lock=1 to lock it, and autoplay=1 to autoplay. The README notes that WeChat Official Accounts, Zhihu, and Xiaohongshu do not support embedding.
A Deeper Look
Three Entry Points for AI
This is what I find most interesting about the project: it is not only for people to look at; it leaves interfaces for AI too.
1. MCP server: scripts/mcp_server.js, which the README says has zero third-party dependencies, with three tools:
| Tool | Purpose |
|---|---|
inspect_place | Look up a place |
inspect_person | Look up a person |
search_atlas | Search the atlas |
2. Agent Skill: skills/jiangshan-atlas/SKILL.md, with a command-line script skills/jiangshan-atlas/scripts/jiangshan.py that can render an image using --year, --place, and --out.
3. llms.txt and the URL protocol: llms.txt is a machine-readable description; the URL protocol supports single points, multiple stops in the same year, and multiple stops across years (years and places paired in order). In the browser there is also window.atlasAPI (locate, inspect, resolvePlace, openPerson, search) and WebMCP.
The three paths map to three uses: have an agent call the tools directly, have an agent generate a picture for a given year and place, or have an agent build a URL for you to open and see the located map. I did not test these in practice; the above follows the README and the directory listing.
Data Sources and Licensing: Read This Part Carefully
The project license is GPL-3.0, but not all data is under the GPL. The README explains:
| Data | Source | License |
|---|---|---|
| Code and self-drawn data | The project itself | GPL-3.0 |
| Polity outlines | Redrawn by hand starting from aourednik/historical-basemaps | Self-drawn parts under GPL-3.0 |
| Commandery, prefecture, and fu boundaries | Derived from CHGIS V6 and Hartwell GIS | Not under the GPL; academic, non-commercial use only; no redistribution |
| Modern provinces | DataV GeoAtlas | See its source |
| Rivers and lakes | Public domain | |
| Terrain | Based on AWS Terrain Tiles (SRTM, GMTED2010, ETOPO1) | See its source |
Practical consequences:
- Check data sources before commercial use or redistribution: GPL-3.0 code does not mean all the data inside is free for commercial use
- When exporting GeoJSON, commandery, prefecture, and fu boundaries are not exported by default; you must add
--with-prefectures, a protection the project sets up on purpose - GeoJSON export covers 403 BCE to 1948 and does not include modern provinces
- Reuse requires crediting "江山时序 Jiangshan Atlas" and the original repo link; the CHGIS citation format is CHGIS, Version: 6. © Fairbank Center …, 2016.
Accuracy: What It Says About Itself
This is where a historical map is most likely to be questioned. The README is clear:
- Historical territories and administrative boundaries are schematic approximations, not survey results, and should not be used as an authoritative basis for borders
- The original sources of early first-level divisions were not recorded
In other words, it suits understanding the broad shifts and the history of places, not serious boundary research, and certainly not as evidence in a disputed question.
The scripts/ directory holds a set of audit and validation scripts, such as validate_atlas.js, audit_sources.js, audit_topology.js, and check_sources.js, which shows the author does validate the data. But I did not read these scripts, so I cannot say what exactly they check or how they fare, and I did not run them.
Repo Layout
index.html,css/,js/: the front end itselfdata/: the atlas data, split intoatlasandsourcesgeojson/: GeoJSON examples and a locate scripttopics/: topic pagesscripts/: build, validation, export, and the MCP serverskills/: the Agent Skillworkers/: contains astatsfolder; I did not read it and am not sure what it is for (if privacy matters to you, take a look yourself)Dockerfile,docker-compose.yml: containerized deployment
Limits and Cautions
- Boundaries are schematic: the README says explicitly they are not an authoritative basis
- Some data has usage limits: prefecture-level boundaries are academic and non-commercial only, and cannot be redistributed
- Export range is limited: GeoJSON stops at 1948 and has no modern provinces
- Some embedding platforms are not supported: WeChat Official Accounts, Zhihu, and Xiaohongshu
- You build the Docker image yourself: it is not published to a registry
- A young project: created in July 2026, with no stable-release promise that I could see, so judge maturity yourself
Project Links and Resources
- 🌟 GitHub: https://github.com/DeanChensj/jiangshan-map
- 🌐 Live site: https://deanchen.me/jiangshan-map/
- 🤝 Contributing:
CONTRIBUTING_ZH.mdin the repo; for data corrections use the issue template, ideally with a source - 📄 License: code and self-drawn data GPL-3.0; prefecture-level data has its own restrictions
Summary
Key Takeaways
- Positioning: a static interactive map of Chinese history, about 2,400 years across 18 periods, with a draggable timeline
- Rich interaction: click a place, a person, or an event; routes of several people can mark shared stretches
- AI-friendly: a local MCP server, an Agent Skill,
llms.txt, and a URL protocol - Mind the data license: code is GPL-3.0, but prefecture-level boundaries are academic and non-commercial only, with no redistribution
- Boundaries are schematic: good for understanding broad change, not for authoritative research
Who This Is For
- Readers of history and poetry who want to see geographic change directly
- Creators of history courses and explainers who need an embeddable interactive map
- Developers curious about how to make a static site friendly to AI; the combination of MCP, a Skill, and
llms.txtis worth studying
Suggested First Steps
Open the live site and try a few entry points: drag the timeline once, click an ancient city you know, then search "李白 杜甫" to see the shared-route markers. For technical detail, read scripts/mcp_server.js and skills/jiangshan-atlas/SKILL.md, which show how a website becomes a tool AI can call. If you plan to use it commercially or redistribute it, read the data sources and licensing section of the README first.
Check out PrimeSkills — a curated marketplace of AI agents and skills that have been validated in real-world, enterprise-grade workflows. No fluff, just what actually works.
Find more useful knowledge and interesting products on my Homepage