One Open Source Project a Day (No. 263): Jiangshan Atlas — A Static Interactive Map of Chinese History, Dragged From 403 BCE to Today, and Queryable by AI

Jiangshan Atlas (江山时序) is a purely static interactive historical map of China covering about 2,400 years, from 403 BCE to the present, across 18 historical periods. Drag the timeline to watch territories change, click an ancient city for its history through the ages, search a person to follow their route, and replay events like the Chu-Han Contention and the An Lushan Rebellion in acts. It ships a local MCP server, an Agent Skill, and llms.txt so AI can query it too. Code is GPL-3.0, but some administrative-boundary data is limited to academic, non-commercial use. About 7.3k Stars.

·10 min read·AI Engineering

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.server or 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 route

Core Capabilities

FeatureDescription
TimelineDraggable 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 territoriesHigh-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 placeClick 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 personSearch 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 eventThe 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 8000

Then open http://localhost:8000.

Deploy with Docker:

docker compose up -d --build

Visit 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:

ToolPurpose
inspect_placeLook up a place
inspect_personLook up a person
search_atlasSearch 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:

DataSourceLicense
Code and self-drawn dataThe project itselfGPL-3.0
Polity outlinesRedrawn by hand starting from aourednik/historical-basemapsSelf-drawn parts under GPL-3.0
Commandery, prefecture, and fu boundariesDerived from CHGIS V6 and Hartwell GISNot under the GPL; academic, non-commercial use only; no redistribution
Modern provincesDataV GeoAtlasSee its source
Rivers and lakesPublic domain
TerrainBased 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 itself
  • data/: the atlas data, split into atlas and sources
  • geojson/: GeoJSON examples and a locate script
  • topics/: topic pages
  • scripts/: build, validation, export, and the MCP server
  • skills/: the Agent Skill
  • workers/: contains a stats folder; 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

  1. Boundaries are schematic: the README says explicitly they are not an authoritative basis
  2. Some data has usage limits: prefecture-level boundaries are academic and non-commercial only, and cannot be redistributed
  3. Export range is limited: GeoJSON stops at 1948 and has no modern provinces
  4. Some embedding platforms are not supported: WeChat Official Accounts, Zhihu, and Xiaohongshu
  5. You build the Docker image yourself: it is not published to a registry
  6. A young project: created in July 2026, with no stable-release promise that I could see, so judge maturity yourself


Summary

Key Takeaways

  1. Positioning: a static interactive map of Chinese history, about 2,400 years across 18 periods, with a draggable timeline
  2. Rich interaction: click a place, a person, or an event; routes of several people can mark shared stretches
  3. AI-friendly: a local MCP server, an Agent Skill, llms.txt, and a URL protocol
  4. Mind the data license: code is GPL-3.0, but prefecture-level boundaries are academic and non-commercial only, with no redistribution
  5. 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.txt is 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