DeanChensj/jiangshan-map 是一个托管在 GitHub 上的开源项目，主要使用 JavaScript 编写，采用 GNU General Public License v3.0 许可证，目前获得 5.2k 个 Star、611 次 Fork。
仓库全名
DeanChensj/jiangshan-map
README 摘要
Chronicles of the Realm · 江山时序 English · 简体中文 (Chinese) · 日本語 (Japanese) An Interactive Historical Atlas of China from the Warring States (403 BCE) to the Present — Scrub Through Time, Trace Ancient Cities, and Walk in the Footsteps of History Play Live Demo (English UI) → https://deanchen.me/jiangshan-map/?lang=en The story behind it (in Chinese): From textbook maps to 1k GitHub stars Why It's Fun to Explore Have…
An Interactive Historical Atlas of China from the Warring States (403 BCE) to the Present — Scrub Through Time, Trace Ancient Cities, and Walk in the Footsteps of History
Have you ever wondered while reading Chinese history or classical poetry:
“Where exactly on today’s map are Jiankang (the Six Dynasties capital), Huangzhou (where Su Dongpo composed the Red Cliffs Rhapsody in exile), Languan Pass in the Qinling Mountains (where Han Yu halted his horse in the snow), or Zhuxianzhen (Yue Fei’s northern campaign frontier)?”
“How many names did Chang’an hold across two millennia, and what pivotal events unfolded on that soil?”
“How did the realm evolve step by step—from the Partition of Jin and the Seven Warring States at the opening of Sima Guang’s Zizhi Tongjian (403 BCE), Qin’s unification campaigns, Emperor Wu of Han opening the Hexi Corridor, High Tang’s Four Garrisons of Anxi, and Yuan’s Xuanzhengyuan jurisdiction over Tibet, to Zeng Jize’s recovery of Ili (1881 CE) and the 20th-century shift from the ‘Begonia Leaf’ (秋海棠) map to the ‘Rooster’ (雄鸡) map?”
Chronicles of the Realm (jiangshan-map) brings together 2,400+ years of Chinese history across 18 historical periods into a single interactive parchment atlas—featuring multi-stage territorial and prefecture snapshots, ancient cities, strategic mountain passes, poetic and battlefield landmarks, chronological milestones, and reigning monarchs & imperial eras. No heavy print atlases required—just drag the timeline and click any city to travel through space and time.
Feature 1: Scrub the Timeline to Watch Realms Rise & Fall, Track Monarchs, and Compare Ancient & Modern Borders
Multi-Polity Confrontations on a Single Canvas: From the Seven Warring States (Qin, Chu, Qi, Yan, Zhao, Wei, Han) alongside Zhou, Yue, Ba-Shu, Zhongshan, and Yiqu, to the Three Kingdoms warlords (Yuan Shao, Cao Cao, Liu Bei, Sun Quan, Gongsun’s Liaodong), Northern & Southern Dynasties, Five Dynasties & Ten Kingdoms, and Song, Liao, Western Xia, Dali, Jin, and the Mongols—all rendered side-by-side in high-contrast traditional parchment hues. Hover over any polity in the bottom-left legend to highlight its territory, or click to zoom straight to it.
Multi-Stage Territorial Evolution & Dashed “Ghost Boundary Diffs”: At every major territorial milestone—such as Qin’s conquest of Ba-Shu (316 BCE), Yan General Qin Kai’s expansion into Liaodong (300 BCE), Ma Yuan’s bronze pillars in Jiaozhi (43 CE), Sima Yi’s campaign in Liaodong (238 CE), Li Jing’s conquest of Tuyuhun (635 CE), the Four Garrisons of Anxi & Wang Xuance’s campaign in Central India (648 CE), Yuan’s Xuanzhengyuan rule over Tibet (1288 CE), Ming’s Hami & Seven Guards West of Jiayuguan (1404 CE), the 1881 Treaty of Saint Petersburg recovering Ili, the 1898 foreign leased territories, the 1945 retrocession of Taiwan, and the 1946 transition from the “Begonia Leaf” (秋海棠) map to the “Rooster” (雄鸡) map—click any milestone or phase dot to switch maps and reveal the previous phase’s dashed vermilion Ghost Boundary Diff so territorial gains and losses are immediately visible.
Inline Reigning Monarch & Imperial Era Display: The timeline dynamically displays the reigning monarch (temple/posthumous title + personal name + reign span, e.g., Emperor Wu of Han · Liu Che, Emperor Taizong of Tang · Li Shimin, Emperor Shengzu of Qing · Xuanye) alongside the exact imperial era year.
Ancient Prefecture Hover Inspection & Modern X-Ray Lens: First-level administrative divisions (Commanderies, Circuits, Routes, and Provinces) are rendered with deduplicated Parchment Casing borders. Zoom in and hover over any prefecture (e.g., Ming Yingtian Prefecture or Three Kingdoms Jingzhou) to inspect its jurisdiction and modern provincial equivalents, or toggle the X-Ray Lens to project modern provincial boundaries directly over the historical map.
Dynamic River Courses, Ancient Lakes & Grand Engineering Works: As you scrub through time, historical shifts of the Yellow River, expanding and shrinking ancient lakes (Yunmeng Marsh, Lop Nur / Puchanghai), Warring States/Qin/Han/Ming Great Walls, Sui-Tang & Grand Canals, the Silk Road, and Zheng He’s maritime routes evolve in lockstep with each era.
Feature 2: Click Any Ancient City or Strategic Pass to Uncover 2,400 Years of History (Trace Place)
Click any ancient city or mountain pass on the map (or double-click anywhere on the canvas) to open its Trace Place genealogy card:
Bilingual City Lore Banner & 2,400-Year Administrative Genealogy: At the top of the card, read a curated poetic epigraph and historical biography for the city; below, trace how its name and administrative jurisdiction evolved across all 18 historical eras—from Warring States and Qin commanderies, Han regional inspectorates, Tang circuits, and Song routes to Yuan/Ming/Qing provinces and modern municipalities—complete with Imperial Capital badges and dynastic seat remarks.
Site-Specific Landmark Events: Beneath each dynasty row, inspect major historical events that took place right on that spot (e.g., Shang Yang’s Reforms and Qin’s Unification at Xianyang, Guan Yu Flooding the Seven Armies at Fancheng, the Xuanwu Gate Incident at Chang’an, or Yue Fei’s Martyrdom at Lin’an). Click the Key Events pill in the top-right of the card to filter for dynasties with major events, and click any event to time-travel straight to that year!
Strategic Mountain Passes & Poetic / Battlefield Landmarks: Explore famous mountain passes—including Hangu Pass, Tongguan, Jianmen Pass, Yanmen Pass, Yumen Pass, Yangguan, and Shanhai Pass—rendered with traditional Hanque gatehouse icons and strategic terrain notes, alongside famous battlefields and literary landmarks such as Red Cliffs (Chibi), Gaixia, Wuzhang Plains, Orchid Pavilion (Lanting), Yueyang Tower, Pavilion of Prince Teng, Languan Pass, Loulan, Lop Nur, and Issyk-Kul.
Feature 3: Person Chronicles — Trace Any Historical Figure Across Time & Space
Click the top-left Universal Search Box (with a rotatable e.g. figure preview and quick-search chips, or type any monarch, general, statesman, monk, or poet such as Cao Cao, Huo Qubing, Sima Qian, Yue Fei, or Zheng He) to open Person Chronicle (点人溯事), plotting every milestone of their life with delicate cartographic hairline arcs and directional ticks across changing dynastic borders:
Qin Shi Huang’s Unification Campaigns (238–221 BCE): From suppressing the rebellion at Xianyang and Wang Jian’s attack on Ye, to the fall of Han, Zhao, Yan, Wei, Chu, and Dai, culminating in the surrender of Qi at Linzi—as you advance stop by stop, watch the six rival kingdoms merge into the Qin Empire right on the map!
Zhang Qian’s Mission to the Western Regions (138–126 BCE): Depart Chang’an, endure over a decade of Xiongnu captivity without surrendering the Han imperial staff, and blaze the trail to Dayuan (Fergana), Kangju, and the Greater Yuezhi.
Zhuge Liang’s Emergence & Northern Expeditions (207–234 CE): From the Three Visits at Longzhong and the alliance at Chaisang before Red Cliffs, to entering Shu, the White Emperor City entrustment, the Southern Campaign across the Lu River, Hanzhong’s Memorial on Deploying the Troops, Mount Qi, and the autumn winds of Wuzhang Plains.
Xuanzang’s Pilgrimage to India (627–645 CE): Slip past Yumen Pass alone across the Moheyan Desert, scale the icy Bedel Pass, cross the Indus, study at Nalanda Monastery, and debate at Kanyakubja (Kanauj) before returning to Chang’an.
Li Bai’s Grand Travels Across Tang China (701–762 CE): From Suyab and boyhood in Shu, sailing out through the Three Gorges at twenty-four, scattering gold in Yangzhou, serving in the Hanlin Academy at Chang’an, meeting Du Fu in Luoyang, receiving amnesty at White Emperor City, to his final years at Dangtu.
Su Shi’s Literary Exile Across Song China (1056–1101 CE): From leaving Meishan for the capital Kaifeng and gazing at the moon in Mizhou, to composing the Red Cliffs Rhapsody in Huangzhou exile, Huizhou, and crossing the sea to Danzhou on Hainan Island.
Wang Yangming’s Unity of Knowledge & Action (1472–1529 CE): From birth in Yuyao and imprisonment in Beijing, to his enlightenment at Longchang in Guizhou, pacifying bandits in Southern Ganzhou, capturing the rebel Prince of Ning in 35 days, teaching at the Tianquan Bridge in Shaoxing, and his final words “This mind is bright and clear; what more is there to say?” at Nan’an.
Each time you step to the next event (‹ / ›, ← / →, or Space to auto-play), the timeline year, reigning monarch, imperial era, and dynastic territories evolve in sync with their footsteps, highlighting the active transition arc alongside bilingual primary-source excerpts and poems written at that exact site.
Feature 4: Easter Egg · Map Pinpoint Challenge — What Imperial Court Rank Would You Earn?
Think you know Chinese historical geography? Click Quiz › in the corner of the Universal Search Box guide bar (or type quiz for Map Pinpoint · Ancient Place Quiz):
Dynastic Historical Clues + Blind Map Pinpointing: City labels are hidden while the prompt asks you to locate an ancient city across a 10-round progressive difficulty deck—accompanied by dynastic historical clues (without spoiling the modern city name). Drop your pin to preview and adjust, click the on-pin ✓ Confirm button to lock in your answer with concentric distance score rings, and earn points based on great-circle distance to the true coordinates!
Complete 10 rounds to receive a traditional imperial cartographic title such as Grand Historian & Master Cartographer (太史令 · 舆图大家), Director of the Bureau of Operations (职方郎中), or Prefectural Retainer (州郡从事).
Put any view of the atlas into a blog post, Notion page, or course site:
Open the atlas and set up the view you want (a year, a regime profile, a place card, or a person’s trajectory). The address bar always mirrors what you see.
Copy the URL and add &embed=1.
Paste it into an <iframe>:
<iframesrc="https://deanchen.me/jiangshan-map/?embed=1&year=1104&trace=101.778,36.617&from=1072&to=1126&lang=en"width="100%"height="480"loading="lazy"style="border:0"title="Chronicles of the Realm · 1104 CE, Northern Song"></iframe>
The embedded map hides the site chrome and keeps only the map, a compact timeline, a title chip, an “Open in Jiangshan Atlas ↗” link, and a note that historical borders are approximate. Readers click once to start panning and zooming, so scrolling your page never gets stuck on the map.
Parameter
Effect
embed=1
Turn on embed mode (required)
year, polity, person, stop, trace, lang
Same as the share links above
from=1072&to=1126
Limit the timeline to this range; the timeline zooms to show only it
lock=1
Freeze the map at year and hide the timeline
autoplay=1
Play a person’s trajectory stop by stop (with person), or play the timeline
WeChat Official Accounts, Zhihu, and Xiaohongshu do not allow iframes; share the plain link there instead.
AI Agent, MCP & LLM Integration
Chronicles of the Realm works out of the box as a historical-geography visualization engine for LLMs, MCP Clients, and AI Agents. Models never need to guess latitude/longitude coordinates—simply extract two semantic parameters from a poem or historical text, year and place, and the atlas automatically resolves ancient/modern place names, centers the camera, renders dynastic borders and multi-stop trajectories, and opens the Trace Place genealogy card:
3. Browser JavaScript API (window.atlasAPI) & In-Browser WebMCP (navigator.modelContext)
In browser automation environments (Playwright) or WebMCP-enabled AI browsers (navigator.modelContext), the page automatically registers jiangshan_locate, jiangshan_inspect, and jiangshan_open_person, and exposes window.atlasAPI:
window.atlasAPI.locate({ year, place, zoom? }): Drives the map to a single location or multi-stop trajectory and returns structured historical-geographic metadata.
window.atlasAPI.inspect({ year, place, person?, stop? }): Read-only query returning the controlling polity, ancient prefecture, modern province/city, leg distances, person events, and canonical shareable URL.
window.atlasAPI.resolvePlace(place, year?): Resolves ancient and modern names for cities, strategic passes, poetic landmarks, and battlefields.
window.atlasAPI.openPerson(person, stop?) & window.atlasAPI.search(query): Opens a person chronicle on the map or searches across the entire atlas.
Run Locally
No dependencies or build steps required. Clone and serve with any static HTTP server:
git clone https://github.com/DeanChensj/jiangshan-map.git
cd jiangshan-map
python3 -m http.server 8000
Then open http://localhost:8000 in your browser.
Run with Docker
No local dependency needed. Build and start with Docker Compose:
docker compose up -d --build
Then open http://localhost:8008 (the port mapping 8008:80 is set in docker-compose.yml).
The image is a plain nginx:alpine that serves this repository as static files: Dockerfile copies the working tree into /usr/share/nginx/html, and .dockerignore keeps the build context small by excluding .git, .github, data/, docs/, scripts/, skills/, Markdown files and geojson/demo.html — the site does not need any of them at runtime.
To use another port, change the ports mapping in docker-compose.yml (e.g. "9000:80") and run docker compose up -d again.
After pulling upstream changes, rebuild with docker compose up -d --build. Without Compose: docker build -t jiangshan-map:latest . then docker run -d -p 8008:80 --name jiangshan-map jiangshan-map:latest.
Note: the image is built locally; it is not published to any registry.
GeoJSON Export (for Leaflet / MapLibre / QGIS)
The app ships its geometry as compact topology-deduplicated VLQ bundles. To use the vector layers in other projects, generate standard RFC 7946 GeoJSON (EPSG:4326, lon/lat) locally; the output goes to geojson/ and is not committed. The export covers 403 BCE to 1948; later years and the modern province layer are not included. The prefecture layer (郡 / 州 / 府) is left out by default because it derives from CHGIS, whose terms forbid redistribution; add --with-prefectures to include it for local academic, non-commercial use, and do not publish the result.
node scripts/export_geojson.js # or: node scripts/export_geojson.js <outDir>
node scripts/export_geojson.js --with-prefectures # adds the CHGIS-derived prefecture layer (local academic use only)
snapshots/<id>.geojson — one file per territorial phase; each feature has a bbox and layer (polity / region, plus prefecture with --with-prefectures), title, title_en, category, tint, anchor.
index.json — every dynasty’s phases with from / to years (negative = BCE, no year 0) and the matching snapshot file.
corridors.geojson (walls, canals, roads, sea routes), settlements.geojson, milestones.geojson, neighbors.geojson, and modern/ (rivers, lakes, hydro labels; appear / vanish give the years historical river courses and lakes are shown).
To look up a point without loading every phase, use geojson/jiangshan-locate.js: it loads index.json plus only the snapshot covering the year, then runs a bbox-filtered point-in-polygon test.
const atlas = JiangshanLocate.create();// or create({ base: '<url of geojson/>' })const hit =await atlas.locate(118.78,32.06,1415);// lon, lat, year
hit.polity.properties.title;// 明
hit.region.properties.title;// 南直隶
hit.prefecture;// null unless exported with --with-prefectures (then 应天府)
After exporting, serve the repository (python3 -m http.server 8000) and open http://localhost:8000/geojson/demo.html for a Leaflet example: drag the year slider, click the map, or open demo.html?year=1415&lon=118.78&lat=32.06 to load, highlight and zoom automatically. Historical borders are schematic approximations, not surveyed boundaries. The data is GPL-3.0 except the prefecture-level boundaries; see Data Sources & License.
Data Sources & License
Code and the data created by this project are released under GPL-3.0. One layer is not: the prefecture-level boundaries derived from CHGIS, which stay under CHGIS’s own terms.
Drawn by hand from historical texts; the source of early versions was not recorded
GPL-3.0
Prefecture-level boundaries (prefecture: 郡 / 州 / 府, incl. Warring States and Qin commanderies)
Derived from CHGIS V6 and the Robert M. Hartwell China Historical GIS, simplified to 0.01° and edited by hand
Not GPL-3.0. Academic, non-commercial use only; do not redistribute. See below
Settlements, milestones, journeys, person chronicles, place lore
Compiled by this project from historical texts
GPL-3.0
Modern provinces
DataV GeoAtlas (Alibaba Cloud)
Subject to DataV GeoAtlas terms
Rivers, lakes, neighbouring countries
Public-domain data
Public domain
Terrain hillshade
Rendered by scripts/build_terrain_tiles.py from AWS Terrain Tiles (public-domain SRTM, GMTED2010, ETOPO1); only shaded images at no finer than about 1 km per pixel are published
Scholarly references (not data sources). Boundaries are checked against historical texts and Tan Qixiang’s The Historical Atlas of China (谭其骧主编《中国历史地图集》). No map images or data from that atlas are included in this repository.
Approximate boundaries. Historical territories and administrative boundaries are schematic approximations of broad jurisdictions, not surveyed borders. Do not cite them as precise or authoritative.
Reusing this project. For the GPL-3.0 layers, credit 江山时序 Jiangshan Atlas with a link to https://github.com/DeanChensj/jiangshan-map and cite the upstream sources above. Screenshots that show the prefecture layer carry the CHGIS terms as well.
Rights holders. If you hold rights in any material here and believe it is used improperly, please open an issue; we will respond and remove it if needed.
Contributing: see CONTRIBUTING.md (中文贡献指南) for repository structure, data conventions, and validation checks.
Report a data error: found a wrong year, place or description? Open a data correction issue and cite a source if you can.
评论