An interactive atlas connects China’s changing borders with historic cities, events and literary landmarks, helping readers place accounts of the past on a map.
Chronicles of the Realm is an interactive atlas that lets readers explore Chinese history through maps, timelines and place records. It connects territorial change with cities, landmarks and historical events, giving readers a geographic way to follow the past.

Screenshot: the project’s README on GitHub
What it is
The project presents Chinese history as an interactive map and timeline. Readers can move through historical periods, inspect territorial boundaries and locate ancient cities, mountain passes, battlefields and literary landmarks. The atlas links those places to administrative histories and events, so a reader can move between a map location and the history associated with it. The map also includes rivers, lakes, coastlines, walls and canals whose routes or shapes vary across periods. This makes the project useful for readers who want geographic context alongside dynastic history or classical writing.
A timeline view brings together competing states and regimes on one map, then lets readers examine particular territorial milestones. Readers can compare a period’s boundaries with the previous phase and inspect historical administrative divisions alongside modern provincial outlines. The atlas also places rulers and historical milestones on the timeline. Its place records follow changing names and jurisdictions across eras, while event records connect locations to episodes in the past. The project therefore serves as both a historical map and a set of linked records for exploring places and events.
How it works
Readers control the map through a timeline. They can drag its handles to focus on a stretch of history, select a milestone to load its map, or use the previous and next controls to move between stages. The interface highlights territorial differences with a dashed boundary layer, which helps readers see where a realm gained or lost land. A legend lets readers isolate a polity’s territory or open a profile with information about its capitals, lifespan and history. Layers add context such as modern provinces, place names and historical features.
The map connects its geography to records that readers can open in place. Selecting a city or pass brings up a genealogy card with its names, administrative jurisdictions and associated events. Selecting an event can take readers to the corresponding year. Search connects the map to historical figures, rulers, cities, eras, landmarks and events. Person Chronicle mode marks a figure’s life events as map pins and follows those stops across changing borders. Readers can also combine journeys, with the interface linking encounters that took place at the same location and year.

Diagram: Drawn by LavX News from the project’s README. Not an official diagram.
Key features
The atlas combines boundaries with physical and built features. Its timeline follows rivers, lakes and coastlines across eras, and includes walls, canals, the Silk Road and maritime routes. Readers can zoom in to inspect prefectures and compare their historical jurisdictions with modern provincial areas. Map profiles describe selected polities, while milestone records connect territorial changes to historical sources. A narration option uses browser speech synthesis to read years and events during playback. These features let readers switch between broad territorial patterns and details tied to a particular place.
Trace Place focuses on the history of a location. Its cards combine a short biography with changes in names and administrative status, and can show major events associated with the site. Person Chronicle follows historical journeys, marking milestones against the map and its changing borders. Event storylines present the movements of opposing sides as a sequence of stops. The project also includes a map quiz: readers use historical clues to locate a place, then receive a distance-based score. Topic Guides offer a reading-oriented way to explore events, routes, battles and changes in administration.
Getting started
Readers can start with the live atlas in a web browser. They can drag the timeline to a period, select a map milestone or search for a place, event or historical figure. Clicking a city or pass opens its place record, while the timeline controls move between historical stages. Readers who want a focused view can zoom into a shorter span or turn off the events layer to step through territorial changes. The README also describes keyboard controls, shareable views and a speech option for browsers that support speech synthesis.
git clone https://github.com/DeanChensj/jiangshan-map.git
cd jiangshan-map
python3 -m http.server 8000
Commands as the project’s README (Run Locally) gives them. Check it for the current steps before you run anything.
Who it is for
Readers of Chinese history can use the atlas to locate places named in historical accounts and trace how those places changed across periods. The place cards connect ancient names and administrative roles to modern geography, while the timeline shows the territorial setting around an event. Readers can inspect city sites, passes and battlefields, then follow related milestones on the map. The same tools help readers compare historical boundaries with modern provinces or examine how geography such as rivers and coastlines appears in different eras.
The project also suits readers of classical poetry and historical biographies. Literary landmarks connect poems and writing to physical locations, while Person Chronicle maps a figure’s travels and life events. Teachers and students can use the timeline to explore the sequence of territorial changes or follow an event storyline stop by stop. Readers who prefer a text-based route can use Topic Guides to browse themes such as famous battles, poetic journeys and administrative change, then jump from a page to its matching map view.
What’s new
The maintainers’ release notes say Version 1.4.0 adds a scale for comparing people active in the same era, links between meeting places and markers for shared years. When several people visit the same city, the map groups those visits into nested rings. The notes also describe refinements to single-person journeys: tracks now form continuous lines across the map, their endpoints align with circle centers, and prefecture marks fade into the background. These changes add detail to the atlas’s tools for comparing journeys and encounters.
The maintainers say the release adds an event mode for tracing the Long March through a sequence of acts and stations. Another mode presents Qin’s conquest of the Guandong states as a sequence of acts while preserving the emperor’s personal timeline. The notes also say that, with the events layer off, timeline stepping and autoplay stop at snapshots where territory changes. They remove isolated stage markers from that view, keeping the controls focused on changes to the map.
Sources: DeanChensj/jiangshan-map · GPL-3.0 · release v1.4.0
Figures come from the GitHub API, read at 16:37 UTC on 20 November 2026. Seven-day star counts are approximate.