Make map diagrams from text

map US Population by State
region-heat Residents (millions) blue

California heat: 39
Texas heat: 30
Florida heat: 23
New York heat: 20
Pennsylvania heat: 13
Illinois heat: 13
Ohio heat: 12
Georgia US heat: 11
North Carolina heat: 11
Michigan heat: 10
New Jersey heat: 9
Virginia heat: 9
Washington heat: 8
Arizona heat: 7
Tennessee heat: 7
Massachusetts heat: 7
Indiana heat: 7
Colorado heat: 6
Maryland heat: 6

Overview

Map diagrams put your data on a real geographic map — shaded regions, points of interest, and routes — for anything where where is the organizing dimension: data shaded by region, offices and sites pinned as points, voyages and flows drawn between them. Map diagrams are geographic concept maps: highlight or shade political subdivisions, drop points of interest (POIs), and connect them with routes or edges. They’re for sharing a concept — territories, presence, voyages — not cartography. The map renders at a fixed, auto-fit position (no pan/zoom), and everything is inferred from the content you reference — basemap, viewport, projection, and ramp. A bare map is already the good-looking map: coastlines, mountain relief on reference maps, region and POI labels, and orientation labels all render by default. v1 boundaries are world countries and US states.

When to use

• map — the positions correspond to real places on Earth, and losing the geography would lose the point.
• clock — if the question is only when (“what time is it for them right now?”), a clock answers it directly. A map answers where they are; it grows live time cards as a side channel, not as its subject.
• heatmap — the rows and columns are named categories and the geography is irrelevant. Conversely, if your rows are states or countries, a grid throws away the adjacency the reader came for — use the map.
• scatter — the two dimensions are just numbers, not latitude and longitude.
• arc — the endpoints of your connections are abstract. Use the map when they have real locations.
• body — you’re labeling parts of a person rather than parts of the Earth.

Syntax

map Title

// names the heat-ramp legend
region-heat Output

// choropleth fill
Florida heat: 42
// categorical fill (via a tag alias)
Texas p: Friendly

// a point of interest
poi Tokyo size: 80
// ordered voyage: origin + arrow legs
route Tokyo
  // ~> = arc leg, -> = straight leg
  ~> Singapore

The first line declares the chart type and an optional title. Type map, name some places, and you’re done — there is no projection, scale, or label directive to set. Cosmetic features are on by default; the only knobs are the bare no-* opt-outs in Turning things off.

How the map is chosen

You never pick a projection — it’s inferred from what you reference. The renderer takes the bounding box of everything (valued or tagged regions, POIs, edge endpoints), pads it, and measures the span:

• US-only → albers-usa (conic; Alaska/Hawaii appear as insets only when you reference them).
• World-scale, with or without data → equirectangular.
• A tight cluster or single continent → conic-equal-area.
• Sub-national US content → mercator.

A map whose content is entirely US — including one built from US cities alone — renders as the conventional US states map: every state outlined, even with no data. Canada and Mexico still count as North-American, US-oriented content; a place outside that scope switches to a world/regional frame. The basemap, projection, and US scoping are always inferred from what you name — there is no override.

Region fill — heat (choropleth)

A subdivision name on its own line with a heat: fills it from a single-hue tint ramp. The ramp auto-fits data-min→data-max with no zero anchor. Subdivisions with no heat value or tag render as the neutral base.

map World Coffee Production
region-heat Bags (millions)

Brazil heat: 69
Vietnam heat: 29
Colombia heat: 14
Indonesia heat: 12
Ethiopia heat: 8
Honduras heat: 6
India heat: 6
Uganda heat: 6
Mexico heat: 4
Peru heat: 4

• region-heat Label names the ramp in the legend.
• A trailing color on region-heat sets the ramp hue — region-heat Bags (millions) blue shades blue instead of the default red.

Region fill — categorical (tags)

Map diagrams use the universal tag model: declare a tag group and apply its alias as a key. The first declared group colours the map automatically — you only need active-tag to pick a different group (or the heat ramp; see below).

map Asia-Pacific Markets

tag Tier as t
  Developed blue
  Emerging green
  Frontier orange

Japan t: Developed
South Korea t: Developed
China t: Emerging
India t: Emerging
Indonesia t: Emerging
Thailand t: Emerging
Malaysia t: Emerging
Vietnam t: Frontier
Philippines t: Frontier
Bangladesh t: Frontier

A region can carry both a heat: and a tag (bivariate). Both are kept as selectable colouring dimensions: the legend shows the heat ramp and each tag group. The heat ramp fills by default whenever any region has a heat value; active-tag <GroupName> switches the fill to a tag group instead. The ramp’s selectable group name is Value (not Heat or the displayed region-heat label).

Direct color (highlight one region)

For a quick highlight without declaring a tag group, drop a trailing color on the region line. It paints a flat fill, ignores the active colouring dimension, and adds no legend entry — the “just make this one stand out” escape hatch. Use tags when the colors are a legend-worthy category.

map Caribbean Cruise Line

Bahamas blue
Cuba orange
Jamaica green
Dominican Republic red
Haiti purple

A direct color wins over both the heat ramp and a tag on the same region. (Put it before any metadata: Cuba orange heat: 90.) Using even one direct region colour also disables automatic political colouring across the whole map.

Points of Interest

poi <name | <lat> <lon>> [as <alias>] [<key>: <value>, …]