obsidian-maps: plotting your notes as a map inside Obsidian Bases

What it does, and the four things it adds

obsidian-maps adds a map layout to Obsidian Bases, so you can display notes as an interactive map view.

The important word in that sentence is Bases. This is not a plugin that adds a map to a note, and it is not a separate canvas. It adds a new layout type to the view system that Bases provides, which means a map is one of several ways of looking at the same query.

That is the design decision that makes the plugin more than a novelty. In Bases, a view is a filtered set of notes rendered in some way, and adding a map layout means the map inherits the filters of the base. A marker is a note that matched, and when the filters change the markers change, because nothing separate is being maintained.

The feature list is four entries. It dynamically displays markers that match your filters. It uses marker icons and colors defined by properties. It loads custom background tiles. And it lets you define default zoom options.

The property-driven icons and colours are the part that makes the map carry information rather than decorate a page. A map of two hundred notes with a hundred different places is a picture, and a map of two hundred notes with three categories shown in three colours is a chart of where your notes are concentrated. That is the same reason a tag cloud beats a tag list.

The plugin is published by Obsidian itself, under the obsidian organisation, with the author recorded as Obsidian and the author URL as obsidian.md, which is worth noting because it means the plugin is maintained alongside the feature it extends rather than by a third party. The licence is MIT, the primary language is TypeScript, and the recent releases are 0.2.2 from 2026-08-01, 0.2.1 from the same day and 0.1.6 from 2025-11-23, with the last push to the repository on 2026-08-03. The full documentation is on the Obsidian Help site under bases and views and map.

Setting up the notes, and the two property formats

The data model is deliberately minimal. You add a coordinates property to each note you want to appear on the map, and both a text property and a list property work.

The text form is a comma-separated pair:

location: 34.13956, -118.38710

And the list form is the same two numbers as entries:

location:
  - 34.13956
  - -118.38710

The two forms are equivalent, and which one you pick is a matter of taste and of what your other tooling expects. A text property is easier to type by hand and easier to grep, a list property is easier to query with a formula and easier to extend to three coordinates later, and the plugin accepts either so you are not forced into a decision before you know what you want.

Then the view is set up. You open a base, add a view, and set its type to Map. In the view options you set Marker coordinates to your property, and markers appear for every note matching the view's filters, and they update as those filters change.

The remaining view options let you set the center coordinates, the default zoom and the zoom limits, and choose the properties that drive each marker's icon and its colour.

The zoom limits are the option worth a second look, because a map that can be zoomed out past the point where the markers are distinguishable is a map that becomes a smear, and a map that cannot be zoomed in far enough is a map that cannot answer a question about one place. Setting both ends of the range is how you keep a map legible for the size of the collection it holds.

The examples directory in the repository is a good reference for the shape of this, with base files and note files for individual Paris locations, including the Centre Pompidou, the Eiffel Tower, the Jardin des Plantes, the Musée d'Orsay, and a Museums base that ties them together.

The background tiles, and the one configuration you will probably change

Maps use OpenFreeMap tiles by default, and to use different tiles you go to Settings, then Maps, and add a background with a tile URL or a style URL. You can set a separate URL for dark mode.

That is a small surface, and the two details in it are the ones that matter. A tile URL is a raster tile server, where you give a URL template and the map fetches images for each tile, and a style URL points at a vector style, which is a document describing the layers, the colours and the glyphs. The plugin renders with MapLibre, which handles vector tiles and raster tiles alike, so both kinds of background work.

The separate dark mode URL is the part that shows the author expects people to care about appearance. A tile server that is designed for a light map will look wrong on a dark Obsidian theme, and a map that ignores the app's theme is a map that breaks the illusion of a single workspace.

The default of OpenFreeMap is a reasonable choice for a plugin distributed by Obsidian, since it requires no account and no key, and a project that wanted a commercial provider by default would be asking every user to sign up before the first marker appeared. If you need a specific provider, the setting is where you put it, and the URL is the only thing you need to change.

The implementation, and what the dependency list reveals

The package manifest is small, and the two runtime dependencies tell you most of the story.

maplibre-gl at version 5.24.0 is the map renderer. It is the open source fork of the Mapbox GL renderer, and it is the reason the plugin can draw vector tiles without a Mapbox account.

The second dependency is the interesting one: @mapbox/mapbox-gl-rtl-text at version 0.3.0, a plugin for right-to-left text. A map of notes is a map of places, and places are not only in Latin scripts. Without right-to-left handling, a marker label in Arabic or Hebrew is rendered in the wrong order inside a map that is otherwise correct, and the fix is a small package that patches the text layout.

That the author reached for it is a good signal about the care taken in the plugin, and it is a signal you would not get from a screenshot.

The build side is esbuild with a TypeScript type check, and the scripts are four. The dev script generates a right-to-left plugin and runs the esbuild config, and the build script does the same plus tsc with noEmit and skipLibCheck and then the esbuild config in production mode. The lint script runs ESLint over src and over package.json, which is the convention for Obsidian plugins because the manifest itself is part of the published artefact. The version script runs a version bump script and then stages manifest.json and versions.json with git add, which is how the plugin repository's published versions list stays in step with the manifest.

The repository also has a scripts/generate-rtl-plugin.mjs step, which is the source of the right-to-left package, so the dependency is vendored rather than taken from a registry, and a tests/ directory, an AGENTS.md, an .npmrc, an eslint.config.mjs, a styles.css, a manifest.json and a versions.json.

Where obsidian-maps is the wrong tool

The first limit is that it needs Bases, and Bases is a specific feature rather than the whole of Obsidian. Someone whose notes are plain markdown in folders, with no base and no properties, gets nothing from this plugin. The map is a view over a query, and without the query there is no view.

The second is that the plugin only sees what the properties say. A note about a place with no coordinates property is invisible to the map, and a note with a wrong coordinate is in the wrong place, and there is no way for the plugin to know. A spatial index built on properties is only as good as the discipline of entering them, and for a large collection that discipline is the real cost.

The third is that the map is a view and not a workspace. You can search, filter and click through, but the map does not give you an editing surface, a route, a distance, or a way to add a marker by clicking where you want it. If the thing you want is to plan a trip from your notes, this is the wrong tool, and it is a common confusion because the word map suggests navigation.

The fourth is the dependency on a tile provider's terms. The default is OpenFreeMap and the alternative is a URL you supply, and a tile server that blocks or throttles a desktop client, or a self-hosted tile server that has to be operated, are both real operational considerations that the plugin's four-line configuration does not mention.

And the fifth is the version line. The releases are 0.2.x and the two most recent landed on the same day in August 2026, with the last push in the same month, which is the rhythm of a young plugin that is still finding its shape. A base view that works today may be rearranged by a later release, and the map layout, being new, is the part most likely to change.

Editorial conclusion

obsidian-maps is worth installing if your notes carry coordinates, because the markers are not a separate index but a projection of the base you already have, so a filter change in the table view and a change in the map view are the same query, and because the marker icons and colours are driven by properties rather than hard-coded, which means the map can show the same categories your notes already classify themselves into. It is the wrong tool if your notes do not have places, and it is the wrong tool if you want a route planner rather than a spatial index. Before you install it, check three things: that Obsidian Bases is the feature you are using, because the plugin adds a layout to a base and not a view to a note, so without Bases it has nothing to attach to; that your coordinates are stored in the property format it expects, either a text property with a latitude and a longitude separated by a comma or a list property with the two numbers as entries, because a coordinate written as a link or as a geohash will simply not produce a marker; and that the tile provider is one you are comfortable with, since the default is OpenFreeMap and a different background is set in the plugin settings with a tile URL or a style URL, and a separate URL can be given for dark mode.

Frequently asked questions

Official sources

1. License: MIT
2. obsidianmd/obsidian-maps on GitHub
3. Project website
4. README
5. Releases