On November 13, 2026, open-source Chinese historical atlas jiangshan-map shipped v1.3.0 on GitHub Releases. If you want to place dynastic borders and military campaigns onto the same interactive map without building GIS software or asking an LLM to guess latitude and longitude, you can open the live web atlas to scrub from 403 BCE to 2026 CE, or wire it straight into Claude and Cursor.
Two-Camp Battle Sandboxes and Shifting Coastlines in v1.3.0
The standout practical addition in v1.3.0 is Event Storylines, a two-camp battle mode. Three major conflicts, the An Lushan Rebellion (?event=anshi&lang=en), the Jingkang Incident (?event=jingkang&lang=en), and the Chu-Han Contention (?event=chuhan&lang=en), each unfold in 10 stops across three acts. Opposing forces appear in distinct colors, and when a conflict crosses dynastic boundaries, the base territory map shifts automatically alongside each step. You can open them from the search box or via milestone pills along the timeline.
Physical geography gets a major upgrade as well. Nine historical sea masks animate shoreline changes across eras around the Bohai Gulf, northern Jiangsu, the Pearl River Delta, and Taiwan's Taijiang Inner Sea before 1823. Zooming in loads on-demand z5-z6 hillshade terrain tiles (about 2 km to 1 km per pixel) derived from public-domain SRTM, GMTED2010, and ETOPO1 elevation datasets, though Data Saver and slow connections skip them automatically. For teachers or presenters, autoplay now includes optional speech synthesis that reads years and events aloud while ducking the background guqin audio, and timeline edge handles zoom into short eras up to 16x. Overall coverage reaches 198 territory snapshots and 526 milestones, while synchronous first-paint scripts drop 35%, from roughly 576 KB to 374 KB gzipped.
Mapping Ming History or Custom Marches Without Writing Code
If your reading covers another dynasty, such as Ming history (1368-1644) or classical poetry routes, you may not need to build a separate atlas. Across its 18 historical periods, jiangshan-map already maps Ming transitions from Hongwu's founding and Xu Da's northern campaign to Yongle's two capitals, frontier garrisons, Zheng He's maritime routes, and Great Wall passes like Shanhai Pass and Jiayuguan Pass. Its catalog of over 124 person chronicles includes Wang Yangming (1472-1529), tracing 10 stops from Yuyao and Longchang to his 35-day campaign against the Prince of Ning, and multi-person search lets you overlay two or three figures on one shared timeline.
For custom trajectories not listed in the menu, the llms.txt specification documents a zero-coordinate URL protocol that resolves Chinese, English, and Pinyin place names automatically:
- Single-site pinpoint:
?year=1415&place=Yingtian&lang=enjumps to Ming Yongle 13 and opens the city's 2,400-year administrative genealogy card, while addinghover=Yingtian Fuhighlights the prefecture polygon. - Same-year multi-stop route:
?year=763&place=Jianwai,Baxia,Wuxia,Xiangyang,Luoyang&lang=endraws numbered vermilion arcs from stop 1 through stop 5 and auto-frames the viewport. - Multi-year space-time route:
?year=1079,1080,1094,1097&place=Huzhou,Huangzhou,Huizhou,Danzhou&lang=enpairs each stop with its exact year and updates the dynastic base map whenever you click a marker. - Converging multi-army routes: separating place lists with a semicolon renders converging paths simultaneously, such as
?year=208&place=Xuchang,Jiangling,Chibi;Chaisang,Fankou,Chibifor the Red Cliffs campaign. - Iframe embedding: appending
&embed=1withfromandtotimeline bounds strips away site chrome for blogs, Notion notes, or course pages without trapping page scroll.
Connecting the Atlas to Claude, Cursor, and Local Scripts
When using an AI assistant to parse primary texts or plot locations from literature, the main GitHub repository offers three integration hooks built around a strict rule: let the model extract year and place, and leave coordinate lookup to the local engine.
For desktop and IDE agents, running node scripts/mcp_server.js starts a local stdio MCP server with zero npm dependencies and under 5ms offline response latency. Adding it to Claude Desktop, Cursor, Windsurf, or Gemini CLI exposes three tools: inspect_place, inspect_person, and search_atlas, returning the active monarch, era name, controlling polity, ancient prefecture, modern province, and canonical share link. Terminal agents can copy skills/jiangshan-atlas into their global skills directory and invoke jiangshan.py to render route PNGs or JSON payloads from a single CLI command, while WebMCP-capable browsers auto-register jiangshan_locate, jiangshan_inspect, and jiangshan_open_person via navigator.modelContext alongside window.atlasAPI.
Three Constraints to Check Before Forking or Relying on It
Scope comes with clear boundaries. Built-in two-camp, three-act battle sandboxes currently cover only the An Lushan Rebellion, Jingkang Incident, and Chu-Han Contention; custom URL routes render numbered arcs and semicolon-separated branches, not scripted campaign acts. The live footer also states that historical borders are schematic approximations rather than surveyed lines, and only 139 of 1,455 records currently cite a primary text inside data/sources/.
Licensing is split cleanly by layer. Application code, hand-drawn polity outlines, settlements, milestones, and terrain hillshade images are released under GPL-3.0. Prefecture-level boundaries (simplified to 0.01 degrees), however, derive from CHGIS V6 and the Robert M. Hartwell China Historical GIS. Those layers remain restricted to academic, non-commercial use and may not be redistributed, which is why scripts/export_geojson.js omits them by default unless you pass --with-prefectures for local non-commercial work.
Deployment itself requires almost no overhead. Written in plain JavaScript with SVG and Canvas rendering and zero framework build steps, the repo runs locally via python3 -m http.server 8000 or Docker Compose on port 8008—just keep any exported CHGIS-derived prefecture layers out of public distributions.
Before cloning the repository to build a custom dynastic map, test your target city and pass list inside a ?year=...&place=... URL on the live site to see how much of your campaign already resolves out of the box.