leaflet-mapping

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Obsidian Leaflet Mapping

Obsidian Leaflet 地图制作

Overview

概述

The Obsidian Leaflet plugin enables interactive maps using LeafletJS without writing JavaScript. Maps are defined in code blocks with YAML parameters and can display real-world locations (OpenStreetMap), custom images (fantasy maps, floor plans), or both layered together. Core principle: Maps are defined declaratively in markdown code blocks. The plugin handles all JavaScript - you just configure parameters. Plugin: https://github.com/javalent/obsidian-leaflet

Obsidian Leaflet插件无需编写JavaScript即可借助LeafletJS创建交互式地图。地图通过代码块中的YAML参数定义，可显示实景地点（基于OpenStreetMap）、自定义图像（如奇幻地图、楼层平面图），或两者叠加显示。 核心原则： 地图以声明式方式在Markdown代码块中定义。插件会处理所有JavaScript相关工作——你只需配置参数即可。 插件地址： https://github.com/javalent/obsidian-leaflet

Prerequisites

前置要求

Required:

Obsidian Leaflet plugin (Community Plugins → Search "Leaflet") Optional (enables advanced features):
Dataview plugin - REQUIRED for
```
markerTag
```
,
```
filterTag
```
,
```
linksTo
```
,
```
linksFrom
```
features
Basic understanding of YAML syntax for code blocks
For real-world maps: coordinates from Google Maps, OpenStreetMap, or GPS devices
For image maps: image file in vault, known reference measurements for scale

必需项：

Obsidian Leaflet插件（社区插件 → 搜索“Leaflet”） 可选项（启用高级功能）：
Dataview插件 - 使用
```
markerTag
```
、
```
filterTag
```
、
```
linksTo
```
、
```
linksFrom
```
功能时必须安装
了解YAML代码块的基础语法
制作实景地图：来自Google Maps、OpenStreetMap或GPS设备的坐标
制作图像地图：库中的图像文件、已知的参考测量比例

Quick Start: Complete Working Example

快速入门：完整可用示例

Goal: Create a map showing all notes tagged

#visited

Step 1: Install plugins

Settings → Community Plugins → Browse
Search "Leaflet" → Install → Enable
Search "Dataview" → Install → Enable (REQUIRED for tag-based markers)
Restart Obsidian (recommended after installing plugins) Step 2: Create a test note Create
```
New York.md
```
:

yaml

---
location: [40.7128, -74.0060]
---

目标： 创建一张显示所有标记有

#visited

标签的笔记的地图 步骤1：安装插件

设置 → 社区插件 → 浏览
搜索“Leaflet” → 安装 → 启用
搜索“Dataview” → 安装 → 启用（基于标签的标记功能必须安装）
重启Obsidian（安装插件后建议重启） 步骤2：创建测试笔记 创建
```
New York.md
```
：

yaml

---
location: [40.7128, -74.0060]
---

New York

My trip notes...

**Step 3: Create the map**
Create `Travel Map.md`:
````markdown
```leaflet
id: my-travels
markerTag: #visited
height: 500px

**Expected result:** Map displays with one marker. Click marker → opens New York note.
**If markers don't appear:** See [troubleshooting checklist](#problem-markers-from-notes-not-appearing) below.

我的旅行笔记...

**步骤3：创建地图**
创建`Travel Map.md`：
````markdown
```leaflet
id: my-travels
markerTag: #visited
height: 500px

**预期结果：** 地图显示一个标记，点击标记即可打开New York笔记。
**如果标记未显示：** 请查看下方的[故障排查清单](#problem-markers-from-notes-not-appearing)。

When to Use

适用场景

Use this skill when:

Creating location-based navigation in vaults (world maps, city maps, building layouts)
Visualizing geographic data from notes (locations with frontmatter)
Displaying custom image maps with markers (RPG campaigns, story locations)
Tracking routes with GPX files or GeoJSON
Building interactive dashboards with spatial data Don't use for:
Simple image display (use standard markdown)
Complex GIS analysis (use dedicated GIS tools)
Real-time map editing (markers are saved to plugin data)

当你需要以下操作时使用本指南：

在笔记库中创建基于位置的导航（世界地图、城市地图、建筑布局）
可视化笔记中的地理数据（带前置元数据的地点）
显示带标记的自定义图像地图（TRPG战役、故事地点）
用GPX文件或GeoJSON追踪路线
构建包含空间数据的交互式仪表盘 不适用场景：
简单的图片展示（使用标准Markdown即可）
复杂的GIS分析（使用专业GIS工具）
实时地图编辑（标记会保存到插件数据中）

Quick Reference

速查参考

Basic Map Structure

基础地图结构

markdown

\`\`\`leaflet
id: unique-map-id              # REQUIRED - any unique string
image: [[ImageFile.jpg]]       # Image map (omit for real-world map)
lat: 50                        # Initial latitude (center point)
long: 50                       # Initial longitude (center point)
height: 500px                  # Map container height
width: 100%                    # Map container width
minZoom: 1                     # Minimum zoom level
maxZoom: 10                    # Maximum zoom level
defaultZoom: 5                 # Initial zoom level
\`\`\`

markdown

\`\`\`leaflet
id: unique-map-id              # 必填 - 任意唯一字符串
image: [[ImageFile.jpg]]       # 图像地图（实景地图请省略此参数）
lat: 50                        # 初始纬度（中心点）
long: 50                       # 初始经度（中心点）
height: 500px                  # 地图容器高度
width: 100%                    # 地图容器宽度
minZoom: 1                     # 最小缩放级别
maxZoom: 10                    # 最大缩放级别
defaultZoom: 5                 # 初始缩放级别
\`\`\`

Map Types

地图类型

Type	Parameters	Use Case
Real-World Map	Omit `image` parameter	OpenStreetMap, city maps, GPS data
Image Map	`image: [[File.jpg]]`	Fantasy maps, floor plans, custom artwork
Multi-Layer Image	`image: [[[Layer1]], [[Layer2]]]`	Maps with toggleable overlays
Custom Tile Server	`tileServer: <url>\|<alias>`	Alternative map styles (Dark, Satellite)

类型	参数	适用场景
实景地图	省略 `image` 参数	OpenStreetMap、城市地图、GPS数据
图像地图	`image: [[File.jpg]]`	奇幻地图、楼层平面图、自定义插画
多层图像地图	`image: [[[Layer1]], [[Layer2]]]`	可切换图层的地图
自定义瓦片服务器	`tileServer: <url>\|<alias>`	替代地图样式（深色、卫星图）

Creating Markers

创建标记

Method	Syntax	Editable	Use Case
Right-click map	Interactive UI	Yes	Manual marker placement
Code block	`marker: type,lat,long,link,desc`	No	Fixed markers in documentation
From note frontmatter	`markerFile: [[Note]]`	No	Single note as marker
From folder	`markerFolder: Path/To/Folder`	No	All notes in folder
From tags	`markerTag: #location`	No	All notes with tag (Dataview required)
From links	`linksTo: [[Note]]`	No	Notes linking to/from (Dataview required)

方法	语法	是否可编辑	适用场景
右键点击地图	交互式UI	是	手动放置标记
代码块定义	`marker: type,lat,long,link,desc`	否	文档中的固定标记
来自笔记前置元数据	`markerFile: [[Note]]`	否	将单个笔记设为标记
来自文件夹	`markerFolder: Path/To/Folder`	否	文件夹中的所有笔记
来自标签	`markerTag: #location`	否	所有带指定标签的笔记（需Dataview）
来自链接关系	`linksTo: [[Note]]`	否	链接到/来自指定笔记的所有笔记（需Dataview）

Real-World Maps

实景地图

Default tile server is OpenStreetMap. Add custom tile servers for different styles:

markdown

\`\`\`leaflet
id: city-map
tileServer: https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}{r}.png|Dark
tileServer: https://tiles.wmflabs.org/hillshading/{z}/{x}/{y}.png|Hills
osmLayer: false                # Turn off default OpenStreetMap layer
\`\`\`

Tile overlays (instead of full layer replacement):

markdown

tileOverlay: https://tiles.example.com/{z}/{x}/{y}.png|Overlay Name|on

Append

|on

to enable overlay by default.

默认瓦片服务器为OpenStreetMap。可添加自定义瓦片服务器以使用不同样式：

markdown

\`\`\`leaflet
id: city-map
tileServer: https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}{r}.png|Dark
tileServer: https://tiles.wmflabs.org/hillshading/{z}/{x}/{y}.png|Hills
osmLayer: false                # 关闭默认OpenStreetMap图层
\`\`\`

瓦片叠加层（替代完全替换图层）：

markdown

tileOverlay: https://tiles.example.com/{z}/{x}/{y}.png|Overlay Name|on

追加

|on

可默认启用叠加层。

Image Maps

图像地图

Critical First Step: Set Bounds

关键第一步：设置边界

Before adding markers, define bounds to prevent coordinate confusion:

markdown

\`\`\`leaflet
id: fantasy-map
image: [[WorldMap.jpg]]
bounds:
  - [0, 0]           # Top-left corner
  - [100, 100]       # Bottom-right corner
\`\`\`

Without bounds, the image stretches to fit arbitrary coordinates. With bounds, latitude/longitude map predictably to image pixels. Common bound strategies:

```
[0,0] to [100,100]
```
- Percentage-based (lat/long are percentages)
```
[0,0] to [width,height]
```
- Pixel-based (match image dimensions)
Custom coordinate system matching your source material

添加标记前，请先定义边界以避免坐标混乱：

markdown

\`\`\`leaflet
id: fantasy-map
image: [[WorldMap.jpg]]
bounds:
  - [0, 0]           # 左上角
  - [100, 100]       # 右下角
\`\`\`

如果不设置边界，图像会拉伸以适配任意坐标空间。设置边界后，纬度/经度可准确映射到图像像素。 常见边界策略：

```
[0,0] 至 [100,100]
```
- 基于百分比的坐标（纬度/经度为百分比）
```
[0,0] 至 [width,height]
```
- 基于像素的坐标（匹配图像尺寸）
与源素材匹配的自定义坐标系统

Multi-Layer Image Maps

多层图像地图

Stack multiple images with independent marker sets:

markdown

\`\`\`leaflet
id: layered-map
image:
  - [[BaseMap.jpg|Base Layer]]
  - [[Roads.png|Roads]]
  - [[Buildings.png|Buildings]]
\`\`\`

Layer control box (top-right) toggles layers. Markers saved per-layer.

叠加多张图像并设置独立的标记集：

markdown

\`\`\`leaflet
id: layered-map
image:
  - [[BaseMap.jpg|Base Layer]]
  - [[Roads.png|Roads]]
  - [[Buildings.png|Buildings]]
\`\`\`

右上角的图层控制框可切换图层，标记会按图层保存。

Zoom Levels on Image Maps

图像地图的缩放级别

Counter-intuitive behavior: Higher

maxZoom

makes map START farther away. Why: Image is placed at

[0,0]

and stretched to fit. Zoom levels control the underlying map, not the image scale. Solution: Set bounds first, then adjust zoom to taste.

markdown

bounds: [[0,0], [100,100]]
minZoom: 1
maxZoom: 6
defaultZoom: 3
zoomDelta: 0.5          # Finer zoom control

反直觉特性：

maxZoom

值越高，地图初始显示视角越远。 原因： 图像会被放置在

[0,0]

位置并拉伸以适配。缩放级别控制的是底层地图，而非图像比例。 解决方案： 先设置边界，再根据需要调整缩放级别。

markdown

bounds: [[0,0], [100,100]]
minZoom: 1
maxZoom: 6
defaultZoom: 3
zoomDelta: 0.5          # 更精细的缩放控制

Markers from Notes

来自笔记的标记

Marker behavior: Clicking a linked marker opens the note (Ctrl/Cmd-click for new pane). Markers automatically link to their source note when created via frontmatter.

标记行为： 点击带链接的标记会打开对应笔记（按住Ctrl/Cmd点击可在新窗格打开）。通过前置元数据创建的标记会自动链接到源笔记。

Finding Coordinates

获取坐标

Real-world maps:

Google Maps: Right-click location → First line shows coordinates
OpenStreetMap: Share button → "Geo URI" contains coordinates
GPS device: Export waypoint coordinates Image maps:
Use
```
bounds: [[0,0], [100,100]]
```
for percentage system
Right-click map after bounds set → coordinates shown on click
Trial-and-error: Place marker, adjust coordinates in frontmatter

实景地图：

Google Maps：右键点击地点 → 第一行显示坐标
OpenStreetMap：点击分享按钮 → “Geo URI”中包含坐标
GPS设备：导出航点坐标 图像地图：
使用
```
bounds: [[0,0], [100,100]]
```
启用百分比坐标系统
设置边界后右键点击地图 → 点击位置会显示坐标
试错法：放置标记后，在前置元数据中调整坐标

Note Frontmatter Format

笔记前置元数据格式

yaml

---
location: [lat, long]           # REQUIRED for automatic markers (array format only)
mapmarker: custom-icon          # Optional: marker type from settings
mapzoom: [minZoom, maxZoom]     # Optional: visibility breakpoints
mapmarkers:                     # Optional: additional markers
  - [type, [lat, long], "Description", minZoom, maxZoom]
  - [type, [lat, long], "Another marker"]
---

Coordinate format: Must be array

[lat, long]

. Strings like

"40.7128, -74.0060"

will NOT work.

yaml

---
location: [lat, long]           # 自动标记必填（仅支持数组格式）
mapmarker: custom-icon          # 可选：来自插件设置的标记类型
mapzoom: [minZoom, maxZoom]     # 可选：标记可见的缩放断点
mapmarkers:                     # 可选：额外标记
  - [type, [lat, long], "描述", minZoom, maxZoom]
  - [type, [lat, long], "另一个标记"]
---

坐标格式： 必须为数组

[lat, long]

。字符串格式如

"40.7128, -74.0060"

无法生效。

Marker Methods

标记方法

Single note:

markdown

markerFile: [[LocationNote]]

Folder (all notes):

markdown

markerFolder: Locations/Cities
markerFolder: Locations/Cities/    # Limit to top-level only (one slash)

By tags (⚠️ REQUIRES DATAVIEW PLUGIN):

markdown

markerTag: #location               # Notes with this tag
markerTag: [#city, #visited]       # Notes with BOTH tags
markerTag:
  - #location                      # Notes with #location OR
  - [#city, #capital]              # Notes with both #city AND #capital

For OR logic: Use separate

markerTag

lines. For AND logic: Use array

[#tag1, #tag2]

. Filter results:

markdown

markerFolder: Locations
filterTag: #important              # Only show important locations

From link relationships (⚠️ REQUIRES DATAVIEW PLUGIN):

markdown

linksTo: [[MainCity]]              # All notes linking to MainCity
linksFrom: [[TravelLog]]           # All notes linked from TravelLog

Multiple files:

linksTo: [[[File1]], [[File2]]]

单个笔记：

markdown

markerFile: [[LocationNote]]

文件夹（所有笔记）：

markdown

markerFolder: Locations/Cities
markerFolder: Locations/Cities/    # 仅限顶层文件（末尾加一个斜杠）

通过标签（⚠️ 需DATAVIEW插件）：

markdown

markerTag: #location               # 带此标签的笔记
markerTag: [#city, #visited]       # 同时带两个标签的笔记
markerTag:
  - #location                      # 带#location标签的笔记，或
  - [#city, #capital]              # 同时带#city和#capital标签的笔记

或逻辑： 使用单独的

markerTag

行。与逻辑： 使用数组

[#tag1, #tag2]

。 过滤结果：

markdown

markerFolder: Locations
filterTag: #important              # 仅显示重要地点

来自链接关系（⚠️ 需DATAVIEW插件）：

markdown

linksTo: [[MainCity]]              # 所有链接到MainCity的笔记
linksFrom: [[TravelLog]]           # 所有被TravelLog链接的笔记

多个文件：

linksTo: [[[File1]], [[File2]]]

Custom Marker Types

自定义标记类型

Define in plugin settings or

markers.json

in same directory:

json

[
  {
    "type": "city",
    "icon": "building",
    "color": "#FF0000",
    "layer": true
  },
  {
    "type": "dungeon",
    "icon": "dungeon",
    "color": "#8B4513",
    "layer": true
  }
]

Then use in frontmatter:

mapmarker: city

在插件设置中定义，或在同一目录下创建

markers.json

：

json

[
  {
    "type": "city",
    "icon": "building",
    "color": "#FF0000",
    "layer": true
  },
  {
    "type": "dungeon",
    "icon": "dungeon",
    "color": "#8B4513",
    "layer": true
  }
]

然后在前置元数据中使用：

mapmarker: city

Overlays

图层叠加

Circular overlays for areas of effect, regions, etc.

圆形叠加层可用于显示影响区域、行政区等。

Interactive Creation

交互式创建

Shift + Right-click → drag → click to set radius

按住Shift + 右键点击 → 拖动 → 点击设置半径

Code Block Definition

代码块定义

markdown

overlay: [color, [lat, long], radius unit, "description"]

Examples:

markdown

overlay: [blue, [32, -89], 25 mi, 'Capital region']
overlay:
  - ['rgb(255,0,0)', [50, 50], 10 km, 'Danger zone']
  - ['#00FF00', [60, 60], 500 ft, 'Safe area']

Note: Overlays draw in order. Smaller overlays behind larger ones become non-interactive.

markdown

overlay: [color, [lat, long], radius unit, "description"]

示例：

markdown

overlay: [blue, [32, -89], 25 mi, '首都区域']
overlay:
  - ['rgb(255,0,0)', [50, 50], 10 km, '危险区域']
  - ['#00FF00', [60, 60], 500 ft, '安全区域']

注意： 叠加层按定义顺序绘制。较小的叠加层如果在较大的叠加层下方，会无法交互。

Overlays from Note Frontmatter

来自笔记前置元数据的叠加层

yaml

---
location: [50, 50]
mapoverlay: [blue, [50, 50], 25 km, "Influence zone"]
---

Or auto-generate from distance tag:

markdown

\`\`\`leaflet
overlayTag: influence
overlayColor: rgba(0,100,255,0.3)
\`\`\`

Note frontmatter:

influence: 50 km

yaml

---
location: [50, 50]
mapoverlay: [blue, [50, 50], 25 km, "影响区域"]
---

或通过距离标签自动生成：

markdown

\`\`\`leaflet
overlayTag: influence
overlayColor: rgba(0,100,255,0.3)
\`\`\`

笔记前置元数据：

influence: 50 km

GeoJSON and GPX

GeoJSON与GPX

GeoJSON

markdown

geojson: [[File.geojson]]|Optional Alias
geojson:
  - [[Routes.geojson]]
  - [[Regions.geojson]]|Regions|[[LinkedNote]]
geojsonColor: #FF0000            # Default color

GeoJSON features can include:

```
title
```
,
```
description
```
, or
```
name
```
→ tooltip
MapBox SimpleStyle properties → styling
Drawn in order specified (layer order matters)

markdown

geojson: [[File.geojson]]|Optional Alias
geojson:
  - [[Routes.geojson]]
  - [[Regions.geojson]]|Regions|[[LinkedNote]]
geojsonColor: #FF0000            # 默认颜色

GeoJSON要素可包含：

```
title
```
、
```
description
```
或
```
name
```
→ 工具提示
MapBox SimpleStyle属性 → 样式设置
按指定顺序绘制（图层顺序很重要）

GPX (GPS tracks)

GPX（GPS轨迹）

markdown

gpx: [[Track.gpx]]
gpx:
  - [[Hike1.gpx]]
  - [[Hike2.gpx]]
gpxColor: #00FF00
gpxMarkers:
  start: start-marker-type       # From plugin settings
  waypoint: waypoint-type

GPX files show:

Route line (colored by speed/elevation/heartrate if data present)
Optional start/end/waypoint markers
Interactive datapoint display (click track)

markdown

gpx: [[Track.gpx]]
gpx:
  - [[Hike1.gpx]]
  - [[Hike2.gpx]]
gpxColor: #00FF00
gpxMarkers:
  start: start-marker-type       # 来自插件设置
  waypoint: waypoint-type

GPX文件会显示：

路线线条（如果有数据，会按速度/海拔/心率着色）
可选的起点/终点/航点标记
交互式数据点展示（点击轨迹）

Common Patterns

常见模式

Campaign Map with Location Notes

带地点笔记的战役地图

markdown

\`\`\`leaflet
id: campaign-world
image: [[WorldMap.jpg]]
bounds: [[0,0], [100,100]]
markerFolder: Locations/Cities
markerFolder: Locations/Dungeons
markerTag: #location
filterTag: #visited
defaultZoom: 3
\`\`\`

markdown

\`\`\`leaflet
id: campaign-world
image: [[WorldMap.jpg]]
bounds: [[0,0], [100,100]]
markerFolder: Locations/Cities
markerFolder: Locations/Dungeons
markerTag: #location
filterTag: #visited
defaultZoom: 3
\`\`\`

Travel Dashboard with GPX

带GPX的旅行仪表盘

markdown

\`\`\`leaflet
id: travel-routes
lat: 40
long: -100
gpxFolder: Travel/2024
gpxColor: #FF6600
gpxMarkers:
  start: trip-start
  waypoint: stop
\`\`\`

markdown

\`\`\`leaflet
id: travel-routes
lat: 40
long: -100
gpxFolder: Travel/2024
gpxColor: #FF6600
gpxMarkers:
  start: trip-start
  waypoint: stop
\`\`\`

Multi-Layer Fantasy Map

多层奇幻地图

markdown

\`\`\`leaflet
id: kingdom-map
image:
  - [[Base.jpg|Terrain]]
  - [[Political.png|Borders]]
  - [[Trade.png|Routes]]
bounds: [[0,0], [1000,1000]]
markerTag: #city
overlayTag: territory
overlayColor: rgba(100,100,255,0.2)
\`\`\`

markdown

\`\`\`leaflet
id: kingdom-map
image:
  - [[Base.jpg|地形层]]
  - [[Political.png|边界层]]
  - [[Trade.png|路线层]]
bounds: [[0,0], [1000,1000]]
markerTag: #city
overlayTag: territory
overlayColor: rgba(100,100,255,0.2)
\`\`\`

Common Mistakes

常见错误

Problem: Markers appear in wrong locations on image maps

问题：图像地图上的标记位置错误

Cause: No bounds defined. Without bounds, Leaflet uses arbitrary coordinate space and your image stretches unpredictably. Why this happens: Image maps overlay images onto Leaflet's default coordinate system. Without explicit bounds, the plugin has no way to map your coordinates (e.g.,

[50, 50]

) to specific pixels on your image. Fix:

Set bounds FIRST before placing any markers:

markdown

bounds: [[0,0], [100,100]]

Delete existing markers (they're in wrong coordinate system)
Place markers again - they'll now appear where you click Finding correct coordinates on image: After setting bounds, Shift+click map to see coordinates, use those in frontmatter.

原因： 未设置边界。没有边界时，Leaflet会使用任意坐标空间，图像会被不可预测地拉伸。 为什么会发生： 图像地图是将图像叠加到Leaflet的默认坐标系统上。如果没有明确的边界，插件无法将你的坐标（如

[50, 50]

）映射到图像的具体像素位置。 修复方法：

在放置任何标记前先设置边界：

markdown

bounds: [[0,0], [100,100]]

删除已有的标记（它们位于错误的坐标系统中）
重新放置标记——现在标记会显示在你点击的位置 在图像上获取正确坐标： 设置边界后，按住Shift点击地图可查看坐标，将这些坐标用于前置元数据。

Problem: Can't zoom in enough / Map starts too far away

问题：无法放大足够的比例 / 地图初始显示视角过远

Cause: Image maps: zoom controls underlying map, not image scale Fix:

Set bounds to match coordinate system
Adjust
```
maxZoom
```
(lower number = closer default view)
Use
```
zoomDelta: 0.5
```
for finer control

原因： 图像地图的缩放控制的是底层地图，而非图像比例 修复方法：

设置与坐标系统匹配的边界
调整
```
maxZoom
```
（数值越小，默认视角越近）
使用
```
zoomDelta: 0.5
```
实现更精细的控制

Problem: Markers from notes not appearing

问题：来自笔记的标记未显示

Quick diagnostic:

Open note with location → does frontmatter show
```
location: [40.7128, -74.0060]
```
? (array format)
Using
```
markerTag
```
/
```
filterTag
```
/
```
linksTo
```
/
```
linksFrom
```
? → Is Dataview plugin installed AND enabled?
Try restarting Obsidian (plugins sometimes need restart to activate) Full checklist:

Note has
```
location: [lat, long]
```
in frontmatter (exact format - array only, not string)
Tags work for both YAML (
```
tags: visited
```
) and inline (
```
#visited
```
in note body)
Coordinates are within map bounds (check min/max lat/long)
Using
```
markerTag
```
,
```
filterTag
```
,
```
linksTo
```
, or
```
linksFrom
```
? Dataview plugin must be installed and enabled (hard dependency)
Verify Dataview works: Create a note with
```
dataview
```
code block to confirm plugin active
Using
```
filterTag
```
? Check note has ALL required tags
Marker zoom breakpoints (
```
mapzoom
```
) within map's
```
minZoom
```
/
```
maxZoom
```
?
For real-world maps: valid lat/long (lat: -90 to 90, long: -180 to 180)
For image maps: coordinates match your bounds system
Map doesn't specify
```
lat
```
/
```
long
```
/
```
defaultZoom
```
? Default centers on [50% world map]. Add
```
showAllMarkers: true
```
to auto-fit all markers.

快速诊断：

打开带地点的笔记 → 前置元数据中是否有
```
location: [40.7128, -74.0060]
```
？（数组格式）
是否使用了
```
markerTag
```
/
```
filterTag
```
/
```
linksTo
```
/
```
linksFrom
```
？ → Dataview插件是否已安装并启用？
尝试重启Obsidian（插件有时需要重启才能激活） 完整排查清单：

笔记前置元数据中有
```
location: [lat, long]
```
（格式必须准确——仅支持数组，不支持字符串）
标签同时支持YAML格式（
```
tags: visited
```
）和内联格式（笔记正文中的
```
#visited
```
）
坐标在地图边界范围内（检查最小/最大纬度/经度）
如果使用
```
markerTag
```
、
```
filterTag
```
、
```
linksTo
```
或
```
linksFrom
```
？必须安装并启用Dataview插件（硬性依赖）
验证Dataview是否正常工作：创建一个带
```
dataview
```
代码块的笔记，确认插件已激活
如果使用
```
filterTag
```
？检查笔记是否包含所有必填标签
标记的缩放断点（
```
mapzoom
```
）是否在地图的
```
minZoom
```
/
```
maxZoom
```
范围内？
对于实景地图：坐标是否有效（纬度范围-90至90，经度范围-180至180）
对于图像地图：坐标是否匹配你的边界系统
地图未指定
```
lat
```
/
```
long
```
/
```
defaultZoom
```
？默认会居中显示在世界地图的50%位置。添加
```
showAllMarkers: true
```
可自动适配所有标记。

Problem: GeoJSON/GPX files not loading

问题：GeoJSON/GPX文件无法加载

Causes:

File path incorrect (use wikilink
```
[[file.geojson]]
```
or relative path)
Large files slow rendering (check console for errors)
JSON syntax errors in GeoJSON Fix: Validate GeoJSON at https://geojsonlint.com/

原因：

文件路径错误（使用维基链接
```
[[file.geojson]]
```
或相对路径）
大文件导致渲染缓慢（检查控制台是否有错误）
GeoJSON存在语法错误 修复方法： 在https://geojsonlint.com/验证GeoJSON的有效性。

Problem: Overlays not interactive / Markers hidden under overlay

问题：叠加层无法交互 / 标记被叠加层遮挡

Cause: Drawing order matters. Overlays and markers drawn later appear on top. Fix:

Overlays obscuring other overlays: Reorder in code block (larger overlays last)
Overlays obscuring markers: Use semi-transparent colors
```
rgba(255,0,0,0.3)
```
or reduce overlay radius
Markers below overlay: Markers from
```
markerTag
```
/
```
markerFolder
```
draw AFTER overlays in code block

原因： 绘制顺序很重要。后绘制的叠加层和标记会显示在上方。 修复方法：

叠加层遮挡其他叠加层：在代码块中重新排序（较大的叠加层放在最后）
叠加层遮挡标记：使用半透明颜色
```
rgba(255,0,0,0.3)
```
或减小叠加层半径
标记在叠加层下方：通过
```
markerTag
```
/
```
markerFolder
```
添加的标记会在代码块中的叠加层之后绘制

Problem: Custom tile server not working

问题：自定义瓦片服务器无法工作

Checklist:

URL contains
```
{z}
```
,
```
{x}
```
,
```
{y}
```
placeholders
Server allows public access (no API key required)
Using
```
tileOverlay
```
instead of
```
tileServer
```
if layering over base map
Check browser console for CORS or 404 errors

排查清单：

URL包含
```
{z}
```
、
```
{x}
```
、
```
{y}
```
占位符
服务器允许公共访问（无需API密钥）
如果是在基础地图上叠加，是否使用了
```
tileOverlay
```
而非
```
tileServer
```
检查浏览器控制台是否有CORS或404错误

Distances and Measurements

距离与测量

Display distance between two points:

Shift/Alt + click location 1
Shift/Alt + click location 2
Distance appears in bottom-left control box Scale and units:

markdown

unit: miles               # Display unit
scale: 1.5               # Scale factor for image maps

For image maps, measure a known distance on your image, calculate scale:

scale = real_distance / measured_pixel_distance

显示两点之间的距离：

按住Shift/Alt点击第一个位置
按住Shift/Alt点击第二个位置
距离会显示在左下角的控制框中 单位与比例：

markdown

unit: miles               # 显示单位
scale: 1.5               # 图像地图的比例因子

对于图像地图，测量图像上的已知距离，计算比例：

比例 = 实际距离 / 测量的像素距离

Advanced Features

高级功能

Initial View from Note

从笔记获取初始视图

markdown

coordinates: [[CityNote]]        # Note with location frontmatter
zoomTag: viewDistance           # Read zoom from note's frontmatter

CityNote frontmatter:

yaml

location: [40, -100]
viewDistance: 50 miles

markdown

coordinates: [[CityNote]]        # 带位置前置元数据的笔记
zoomTag: viewDistance           # 从笔记前置元数据读取缩放级别

CityNote前置元数据：

yaml

location: [40, -100]
viewDistance: 50 miles

Marker Zoom Breakpoints

标记缩放断点

Show/hide markers at zoom levels (prevent clutter):

yaml

mapzoom: [3, 7]          # Only visible between zoom 3-7

Or per-marker in code block:

markdown

marker: city,40,-100,[[Note]],"Description",3,7

在指定缩放级别显示/隐藏标记（避免界面杂乱）：

yaml

mapzoom: [3, 7]          # 仅在缩放级别3-7之间可见

或在代码块中为单个标记设置：

markdown

marker: city,40,-100,[[Note]],"描述",3,7

Draw Mode

绘制模式

markdown

draw: true               # Enable drawing tools
drawColor: #FF0000       # Default shape color

Right-click drawn shapes to edit/delete. Shapes saved to map instance.

markdown

draw: true               # 启用绘图工具
drawColor: #FF0000       # 默认图形颜色

右键点击绘制的图形可编辑/删除。图形会保存到地图实例中。

Dark Mode

深色模式

markdown

darkMode: true           # CSS filter inversion

Customize in CSS snippet targeting

.leaflet-container .dark-mode

markdown

darkMode: true           # CSS滤镜反转

可在CSS代码段中通过

.leaflet-container .dark-mode

自定义样式。

Real-World Impact

实际应用案例

Use cases from community:

TTRPG campaigns: World maps with 100+ location notes, auto-updating as players discover areas
Research: GeoJSON datasets visualized with linked analysis notes
Travel journals: GPX tracks from Apple Health + journal entries as markers
Urban planning: Building layouts with image overlays for different floors
Story writing: Character location tracking across plot timeline Performance notes:
50+ markers: Minimal impact
200+ markers: Noticeable load time
Large GeoJSON/GPX: Consider splitting files
Multiple maps per note: Works fine, independent instances

社区用户的使用场景：

TRPG战役： 带100+地点笔记的世界地图，随着玩家探索自动更新
研究： 可视化GeoJSON数据集，并链接到分析笔记
旅行日志： Apple Health导出的GPX轨迹 + 作为标记的日志条目
城市规划： 带不同楼层图像叠加层的建筑布局
故事创作： 追踪角色在剧情时间线中的位置 性能说明：
50+标记：影响极小
200+标记：加载时间会明显增加
大型GeoJSON/GPX：建议拆分文件
单篇笔记包含多个地图：可正常工作，各实例相互独立