Obsidian Leaflet

> Development Status: Maintenance Mode > > Due to a glut of high priority Javalent plugin projects, this plugin is now entering maintenance mode for the time being. This is not a permanent status. > - PR's will be reviewed. > - Yay bugs will be reviewed and worked if able. > - Feature Requests will not be worked.

---

Adds interactable mapping functionality to Obsidian.md, using Leaflet.js

Proof of concept currently. May not work as expected. Currently only tested on Windows & Mac.

Read this in other languages: 简体中文.

Working with the plugin & example

A map can be created with a leaflet code block. For example:

```leaflet
id: leaflet-map
image: [[Image.jpg]]
height: 500px
lat: 50
long: 50
minZoom: 1
maxZoom: 10
defaultZoom: 5
unit: meters
scale: 1
marker: default, 39.983334, -82.983330, [[Note]]
darkMode: true
```

Options

> 📝 Using Links > > Several parameters below are for providing links to the map, whether that be for images, marker files, etc. > > In all cases, either Obsidian's Wikilinks ([[Link]]) or standard markdown links ([Link](./path/to/file)) may be provided.

Option	Description	Default
id	Unique identifier (can be anything). Required.
image	Direct URL/file path to an image file to be used as the map layer.	OpenStreetMap map
tileServer	Add additional tile servers as different layers
tileSubdomains	Add Available subdomains for additional tile servers concurrent requests. Spilt by ',', etc. 'a,b,c'	a,b,c
tileOverlay	Add additional tile servers an overlay over the base map.
osmLayer	Turn off the OpenStreetMap layer (only usable if additional Tile Servers have been provided)
lat	Default latitude to display when rendering.	50% (image) / 39.983334 (open street map)
long	Default longitude to display when rendering.	50% (image) / -82.983330 (open street map)
height	Height of the map element. Can be provided in pixels or percentage of note height.	500px
width	Width of the map element. Can be provided in pixels or percentage of note width.	100%
minZoom	Minimum allowable zoom level of the map.	1
maxZoom	Maximum allowable zoom level of the map.	10
defaultZoom	Map will load zoomed to this level.	5
zoomDelta	Zoom level will change by this amount when zooming.	1
zoomFeatures	The map will automatically fit all GeoJSON and GPX features
unit	Unit to display distances in	meters
scale	Scale factor for image map distance calculation.	1
marker	Create immutable markers on the map
commandMarker	Create immutable markers that execute commands
markerFile	Create immutable marker from a note's frontmatter
markerFolder	Create immutable markers from all of the notes in the given Paths (relative or absolute to the Vault-Root). Limit Depth by appending one '/' per Folder-Level
markerTag*	Create immutable markers from all of the notes with the given tags.
filterTag*	Filter what files are used to create markers. Only markers that match the tags will be used.
linksTo*	Create immutable markers from all of the notes linking TO a note
linksFrom*	Create immutable markers from all of the notes linking FROM a note
darkMode	Invert map colors	false
overlay	Add a circle overlay to the map
overlayTag	Define a YAML tag to search for in specified marker notes
overlayColor	Change default overlay color	blue
bounds	Set image map bounds to specified coordinates instead of default
coordinates	Read location data from a note and use it as initial coordinates
zoomTag	Read distance-to-zoom data from a note and use it as default initial zoom
geojson	Load multiple *.GeoJSON file-Paths in Json or YAML Syntax into this map. Relative Paths to the current doc start with . (dot).
geojsonColor	Change the default color of the GeoJSON features.	#3388ff
geojsonFolder	Search in multiple folders (Json or YAML Syntax) for *.geojson or *.json files to load into this map. Relative Paths start with . (Dot). Limit Subfolder Depth by appending one Slash per Folder-Level
gpx	Load GPX files onto maps.
gpxMarkers	Set default start, stop and waypoint markers
gpxColor	Control default GPX color	#3388ff
gpxFolder	Parse a folder for .gpx files to load to the map.
imageOverlay	Add an image overlay to the map.
draw	Enable the draw controller on the map.	true
drawColor	Default color that new shapes will be drawn with	#3388ff
showAllMarkers	Map will open showing all markers.	false
preserveAspect	If the note pane the map is in is resized, the map will resize itself to maintain its initial aspect ratio.	false
noUI	No controls will be added to the map.	false
lock	Control whether the map will start locked or unlocked	false
recenter	Forces map to stay re-center itself after panning.	false
noScrollZoom	Turns off scrollwheel zooming.	false

> *: Requires the DataView plugin.

YAML syntax

As of version 3.11.0, all parameters may be defined using YAML syntax instead of using multiple of the same tag. The original syntax will still work, but the two cannot be combined.

For example:

```leaflet
image:
    - [[Image 1]]
    - [[Image 2]]
    - [[Image 3]]
marker:
    - [, , , ]
    - [, , , ]
```

Marker Tags in YAML

YAML considers the # symbol to be a comment, so the markerTag or filterTag parameters must either be wrapped in quotes ("#tag") or defined without the # symbol.

Links

I

Map IDs

As of 3.0.0, map ids are required. If a note with a old map block is opened, the plugin will warn you that the map now requires an ID.

Once an old map is given an ID, the plugin will try to associate the marker data with the new map.

The first time you open the plugin after updating to 3.0.0, a backup of your marker data will be created in case you need to downgrade. If you run into issues, please create an issue on Github.

Initial Map View

Initial Coordinates

The map will open to the latitude and longitude defined using lat and long. If not provided, it will default to the latitude and longitude defined in settings.

Alternatively, the latitude and longitude may be defined using the coordinates parameter. Coordinates may be defined as an array of numbers, or as a wikilink to a note that has a location frontmatter tag:

coordinates: [36, -89]
coordinates: [[Note with Location Frontmatter]]

Initial Zoom Level

> ⚠️ Using an Image Map? > > Zoom levels and image maps may be a little unintuitive. > > Check out Zooming with Image Maps below.

The initial zoom level of the map may be set using the defaultZoom parameter. This must be a number between the minZoom and maxZoom parameters - if outside of them, it will be set to the nearest parameter.

Alternatively, if a coordinates note has been defined, the initial zoom level may be read from that note's frontmatter as .

For example, if a note has the following frontmatter:

### Note With Frontmatter.md
---
location: [-36, 89]
nearby: 100 mi
---

and the map was defined like this:

coordinates: [[Note With Frontmatter]]
zoomTag: nearby

Then the map will read the nearby tag, recognize it is 100 miles, and set the map's initial zoom to the closest level that will display 100 miles (this depends on minZoom, maxZoom, and zoomDelta).

Real World Maps

Real world maps are created if the image parameter is not provided. These maps by default will load the OpenStreetMap map, but additional tile servers can be provided using the tileServer parameter.

It is up to you to ensure that the tile servers you use are publically usable.

At this time, tile servers requiring API access are not usable.

If additional tile servers are provided, the OpenStreetMap layer can be turned off using the osmLayer: false parameter.

Tile Servers

As mentioned above, additional tile servers can be added using the tileServer and tileOverlay parameter. Both have the same syntax:

tileServer: |

For example:

tileServer: https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}{r}.png|Dark

---

tileServer:

-   https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}{r}.png|Dark
-   https://tiles.wmflabs.org/hillshading/{z}/{x}/{y}.png|Hills

Tile servers specified in tileServer will be added as additional layers that can be fully switched to.

Tile Overlays

Tile servers specified as tileOverlay instead as tileServer will be added as overlays that will load on top of the base map.

Tile overlays can be set to default on by appending |on to the end:

tileServer: https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}{r}.png|Dark|on

Tile Subdomains

Add Available subdomains for additional tile servers concurrent requests. Spilt by ',', etc. 'a,b,c'.

tileSubdomains: ,,

For example:

osmLayer: false
tileServer: https://webrd0{s}.is.autonavi.com/appmaptile?lang=zh_cn&size=1&scale=1&style=8&x={x}&y={y}&z={z}
tileSubdomains: 1,2,3

---

So that map will load map data from below urls: https://webrd01.is.autonavi.com/appmaptile?lang=zh_cn&size=1&scale=1&style=8&x={x}&y={y}&z={z} https://webrd02.is.autonavi.com/appmaptile?lang=zh_cn&size=1&scale=1&style=8&x={x}&y={y}&z={z} https://webrd03.is.autonavi.com/appmaptile?lang=zh_cn&size=1&scale=1&style=8&x={x}&y={y}&z={z}

Image Maps

> ⚠️ Making an Image Map? > > For images maps, it is highly recommended that you set your bounds first. > > This will make working with your images much easier! > > Read the discussion about the process. Josh Plunkett has also made a great video breaking down the process here.

Image Map URL / file path

Image maps can be loaded one of three ways:

1. Direct URL (e.g., https://i.imgur.com/jH8j3mJ.jpg)
2. Obsidian URL (e.g., obsidian://open?vault=VaultName&file=Path/To/Image.jpg)
3. Obsidian wikilink of image (e.g., [[Image.jpg]])

Zooming with Image Maps

You may notice that basic image maps and zooming do not necessarily behave the way you think they would. For instance, you may find that setting a higher max zoom value just makes the map start farther away, instead of actually allowing you to zoom in more.

This is because of the way image maps are essentially a hack on top of the LeafletJS module. There is still an underlying map that still has its latitude and longitude, it just can't be seen. The image is then drawn on top of that map (centered at [0, 0]) and then stretched to fit. If you change parameters (such as the zoom levels), the underlying map is changed... but the image is still placed at [0, 0] and stretched to fit!

Instead, the image bounds need to be set for your map. This tells Leaflet exactly what coordinates your image should be placed at on the underlaying map layer. No matter how the map instance changes, the image will be in the same spot and the same size, every time!

Multi-Image Maps

Images can be layered on top of each other by providing multiple images to the plugin:

```leaflet
id: Map With Layered Images
image:
    - [[Image1.jpg|Optional Alias]]
    - [[Image2.jpg]]
    - [[Image3.jpg]]
```

This will generate a map with 3 layers. Image 1 will be on top, Image 2 in the middle, and Image 3 on bottom. The images will be aligned around their center points.

The control box in the top right of the map will allow you to change layers.

Markers can be created and saved on each layer separately from one another.

If given an alias, the layer control box will display the given name instead of the file name.

Bounds

Custom bounds may be given to an image map using the bounds parameter:

```leaflet
image: [[Image.jpg]]
bounds:
    - [, ]
    - [, ]
```

This will cause the latitude and longitude of the image map to be updated to fit within the bounds. This will skew the image if the provided bounds do not match the aspect ratio of the image.

Any markers or overlays defined on the map will not be updated.

Latitude and Longtitude of Image Maps

Because an image map does not have a true coordinate system, the latitude and longitude provided must be given as a percentage from the top left corner of the image.

This setting may seem to not do anything without changing the default zoom level of the map.

Unit and Scale

If provided, the plugin will scale the calculated distance between two points by scale and display the result as xxx unit.

On real-world maps, only unit: is required. It will attempt to scale the measurement from meters to unit.

Markers

New markers can be added to the map by right clicking.

If any additional marker types have been created in plugin settings or a markers.json file in the same directory, a list will appear to choose from.

Once a marker has been created, it can be dragged to a different location.

Markers created on the map will be saved to the map instance. Marker data saved this way will persist as long as the map is associated with a note - if the map blocks are removed from notes, or if all of the notes containing map blocks are removed, the data associated with it will be deleted after 7 days.

Marker Zoom Level Breakpoints

Markers given zoom level breakpoints will be removed from the map when the map is zoomed above or below the breakpoints.

These breakpoints can be set in right-click menu of markers created on the map as well as using parameters for markers created in the source block (see Objects Defined in the Code Block for more information).

Be careful! Make sure the breakpoints are within the map's zoom boundaries, otherwise the marker might never be displayed!

Marker Coordinates

Alt or Shift-clicking on a marker will reveal its coordinates.

Marker Links

A marker can also point to a note; right-click on it, and a popup will appear. The target can be entered as the name of the note. Additionally, headers or blocks within a note can be the target of a marker:

Note

Note#Header1

If you have multiple notes with the same name, you should specify the direct path to the note. Otherwise, the map may not open the one you expect.

Once linked, a click will open the note (Ctrl/Cmd-click to open in new window).

Additionally, markers can be created by dragging a note from the file tree and dropping it on the map.

Marker links can also be set to external websites. Clicking the marker will open the website.

Obsidian Commands as Links

Markers links can also be set to a defined Obsidian command from the command palette one of two ways.

The command must be the full name of the command as it appears in the palette.

Setting a marker link to a command will execute the command when the marker is clicked.

> ##### Warning > > Using a command as a marker target could have unintended consequences. > > Please see this issue for reference.

Defined in Code Block

Use commandMarker: instead of marker:

Created on Map

Turning on the Command Marker toggle.

Bulk Editing

As of version 3.9.0, a bulk-edit button has been added to the map. Clicking this button will open a modal allowing for easy editing of all the mutable markers defined on the map.

Overlays

Overlays may be added to the map by Shift-right clicking, dragging the mouse to set the radius, and clicking again. Hitting Escape will cancel the drawing and remove the overlay. Overlays added to the map in this manner are saved to the map instance just like the markers, and will be recreated when the map is re-opened.

Additionally, overlays may be specified in the source block using the overlay parameter, as so:

`overlay: [, [, ], ,