mirror of
https://gitlab.com/mrubli/hugo-mod-leaflet.git
synced 2025-10-07 01:54:24 +00:00
217 lines
8.5 KiB
Markdown
217 lines
8.5 KiB
Markdown
# hugo-mod-leaflet: Leaflet integration for Hugo
|
|
|
|
This module provies a number of Hugo shortcodes for easy embedding of maps into Hugo-based websites.
|
|
|
|
## Table of contents
|
|
|
|
[TOC]
|
|
|
|
## Example
|
|
|
|
Here's an example use of the map shortcodes provided by hugo-mod-leaflet:
|
|
|
|
```go-html-template
|
|
{{< leaflet-map resizable=false >}}
|
|
{{< leaflet-layer id="ch.swisstopo.pixelkarte-farbe" selectorPosition="bottomleft" >}}
|
|
{{< leaflet-layer id="ch.swisstopo.swissimage" >}}
|
|
{{< leaflet-layer id="ch.swisstopo.swisstlm3d-wanderwege" >}}
|
|
|
|
{{< leaflet-scale position="bottomright" >}}
|
|
|
|
{{< leaflet-track path="track.gpx" color="DarkRed" >}}
|
|
|
|
{{< leaflet-elevation-profile expanded=true resizable=true width=300 height=150 >}}
|
|
{{< /leaflet-map >}}
|
|
```
|
|
|
|
And below is how this might render:
|
|
|
|
{width=792px}
|
|
|
|
## Documentation
|
|
|
|
### Getting started
|
|
|
|
An [example website is available](https://gitlab.com/mrubli/hugo-mod-leaflet-example/) that illustrates how to use hugo-mod-leaflet in your own Hugo website.
|
|
In a nutshell:
|
|
|
|
1. Add a dependency to `gitlab.com/mrubli/hugo-mod-leaflet.git` in your configuration (typically `hugo.toml` or `hugo.yaml`).
|
|
2. Find out how the theme of your choice lets you add code to the site's `<head>` section. A good candidate to look is `layouts/_default/baseof.html` or other files in the same directory. (The example website [uses](https://gitlab.com/mrubli/hugo-mod-leaflet-example/-/blob/master/layouts/partials/site-scripts.html) the `layouts/partials/site-scripts.html` customization point of the [Ananke theme](https://github.com/theNewDynamic/gohugo-theme-ananke).)
|
|
3. Invoke the `leaflet-loader` shortcode from the `<head>` section. Typically, you'd do this with a snippet like this one:
|
|
```
|
|
{{ if .HasShortcode "leaflet-map" }}
|
|
{{ partial "leaflet-loader" . }}
|
|
{{ end }}
|
|
```
|
|
4. Now you can use the shortcodes provided by hugo-mod-leaflet in your content files.
|
|
|
|
### Shortcodes
|
|
|
|
The current shortcode documentation is contained at the top of [leaflet-map.html](layouts/shortcodes/leaflet-map.html) but is reproduced here for convenience:
|
|
|
|
#### Syntax summary
|
|
|
|
```go-html-template
|
|
{{< leaflet-map centerLat=FLOAT centerLon=FLOAT zoom=INT width="STRING" height="STRING" resizable=BOOL maximizable=BOOL freezable=BOOL freezeOptions="STRING" >}}
|
|
{{< leaflet-layer id="STRING" apiKey="STRING" >}}
|
|
{{< leaflet-marker lat=FLOAT lon=FLOAT >}}
|
|
{{< leaflet-track path="URL" title="STRING" downloadable=BOOL >}}
|
|
{{< leaflet-scale >}}
|
|
{{< leaflet-elevation-profile expanded=BOOL resizable=BOOL width=INT height=INT minWidth=INT minHeight=INT maxWidth=INT maxHeight=INT >}}
|
|
{{< /leaflet-map >}}
|
|
```
|
|
|
|
#### Map options
|
|
|
|
```
|
|
centerLat/centerLon:
|
|
Center point coordinates of the map as decimal values. Optional iif tracks or markers are given.
|
|
zoom:
|
|
Zoom level of the map. Optional iif tracks or markers are given.
|
|
width:
|
|
Width of the map, including CSS units (e.g. "50%", "300px").
|
|
Optional, defaults to "auto".
|
|
height:
|
|
Height of the map, including CSS units (e.g. "50%", "300px").
|
|
Optional, defaults to "50vh".
|
|
resizable:
|
|
Boolean value indicating whether the map should be drag & drop resizable.
|
|
Optional, defaults to true.
|
|
maximizable:
|
|
Boolean value indicating whether the maximize button should be displayed.
|
|
Optional, defaults to true.
|
|
freezable:
|
|
Boolean value indicating whether the map should be frozen on page load to avoid scroll capture.
|
|
Optional, defaults to true.
|
|
freezeOptions:
|
|
A string containing a JSON object (without its braces) that contains options for Leaflet.Freezy.
|
|
See https://gitlab.com/mrubli/leaflet-freezy#options for details.
|
|
Optional, defaults to: "freezeButtonInnerHtml: 1500"
|
|
Example: freezeOptions="hoverToThawDuration: 500, freezeButtonInnerHtml: '🥶'"
|
|
Example: freezeOptions=" " (to avoid the hugo-mod-leaflet default and use Leaflet.Freezy's defaults instead)
|
|
```
|
|
|
|
#### Layer options
|
|
|
|
```
|
|
id:
|
|
Name of the layer. Supported base layers:
|
|
- org.openstreetmap.standard:
|
|
https://www.openstreetmap.org/
|
|
- com.thunderforest.cycle: ①
|
|
https://www.thunderforest.com/maps/opencyclemap/
|
|
- com.thunderforest.outdoors: ①
|
|
https://www.thunderforest.com/maps/outdoors/
|
|
- com.thunderforest.landscape: ①
|
|
https://www.thunderforest.com/maps/landscape/
|
|
- ch.swisstopo.pixelkarte-farbe: ②
|
|
https://map.geo.admin.ch/?topic=swisstopo&bgLayer=ch.swisstopo.pixelkarte-farbe&lang=en
|
|
- ch.swisstopo.swissimage: ②
|
|
https://map.geo.admin.ch/?topic=swisstopo&bgLayer=ch.swisstopo.swissimage&lang=en
|
|
Supported overlays:
|
|
- ch.swisstopo.swisstlm3d-wanderwege: ②
|
|
https://map.geo.admin.ch/?topic=swisstopo&bgLayer=ch.swisstopo.pixelkarte-farbe&lang=en&layers=ch.swisstopo.swisstlm3d-wanderwege&layers_opacity=0.8
|
|
- ch.astra.mountainbikeland: ②
|
|
https://map.geo.admin.ch/?topic=swisstopo&bgLayer=ch.swisstopo.pixelkarte-farbe&lang=en&layers=ch.astra.mountainbikeland&layers_opacity=0.6
|
|
- ch.astra.veloland: ②
|
|
https://map.geo.admin.ch/?topic=swisstopo&bgLayer=ch.swisstopo.pixelkarte-farbe&lang=en&layers=ch.astra.veloland&layers_opacity=0.6
|
|
- ch.swisstopo.schneeschuhwandern: ②
|
|
https://map.geo.admin.ch/?topic=swisstopo&bgLayer=ch.swisstopo.pixelkarte-farbe&lang=en&layers=ch.swisstopo.schneeschuhwandern
|
|
- ch.swisstopo-karto.schneeschuhrouten: ②
|
|
https://map.geo.admin.ch/?topic=swisstopo&bgLayer=ch.swisstopo.pixelkarte-farbe&lang=en&layers=ch.swisstopo-karto.schneeschuhrouten&layers_opacity=0.8
|
|
Notes:
|
|
① API key required.
|
|
② Uses EPSG-2056 (Swiss CH1903+/LV95) projection. Cannot be combined with EPSG3857 (WGS 84) map layers.
|
|
apiKey:
|
|
API key for tile access.
|
|
selectorPosition:
|
|
Position of the layer selector button. One of: "topleft", "topright", "bottomleft", "bottomright"
|
|
Optional, defaults to "bottomleft". If specified for more than one layer, the last one wins.
|
|
```
|
|
|
|
#### Marker options
|
|
|
|
```
|
|
lat/lon:
|
|
Coordinates of the marker as decimal values.
|
|
```
|
|
|
|
#### Track options
|
|
|
|
```
|
|
path:
|
|
Absolute or relative path of the .gpx file to render as a track.
|
|
title:
|
|
Name of the track, used e.g. to render the 'Download GPX' button when multiple tracks are present.
|
|
color:
|
|
Color to use for rendering the track.
|
|
Optional, defaults to DeepPink.
|
|
opacity:
|
|
Opacity to use for rendering the track.
|
|
Optional, defaults to 0.7.
|
|
downloadable:
|
|
Boolean value indicating whether there should be a 'Download GPX' button for this track.
|
|
Optional, defaults to true.
|
|
```
|
|
|
|
#### Scale options
|
|
|
|
```
|
|
position:
|
|
Position of the scale. One of: "topleft", "topright", "bottomleft", "bottomright"
|
|
Optional, defaults to "bottomright".
|
|
```
|
|
|
|
#### Elevation profile options
|
|
|
|
```
|
|
resizable:
|
|
Boolean value indicating whether the elevation profile box should be drag & drop resizable.
|
|
Optional, defaults to false.
|
|
expanded:
|
|
Boolean value indicating whether the elevation profile should be expanded by default.
|
|
Optional, defaults to true.
|
|
width:
|
|
Width of the elevation profile.
|
|
Optional, defaults to 360.
|
|
height:
|
|
Height of the elevation profile.
|
|
Optional, defaults to 180.
|
|
minWidth:
|
|
Minimum width of the elevation profile if resizable.
|
|
Optional.
|
|
minHeight:
|
|
Minimum height of the elevation profile if resizable.
|
|
Optional.
|
|
maxWidth:
|
|
Maximum width of the elevation profile if resizable.
|
|
Optional.
|
|
maxHeight:
|
|
Maximum height of the elevation profile if resizable.
|
|
Optional.
|
|
|
|
Note: Elevation profiles are only supported if exactly one track is present.
|
|
```
|
|
|
|
### Configuration options
|
|
|
|
There are a number of module-specific options you can add to your site configuration under the `params.modules.leaflet` key.
|
|
For example, in a YAML config file:
|
|
|
|
```yaml
|
|
params:
|
|
modules:
|
|
leaflet:
|
|
com_thunderforest_outdoors:
|
|
apiKey: YOUR_API_KEY_GOES_HERE
|
|
com_thunderforest_cycle:
|
|
apiKey: YOUR_API_KEY_GOES_HERE
|
|
com_thunderforest_landscape:
|
|
apiKey: YOUR_API_KEY_GOES_HERE
|
|
```
|
|
|
|
|
|
| Key | Description |
|
|
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `<layer_id>.apiKey` | API key for the layer with the given ID. Note that the layer ID is the same as in the `leaflet-layer` shortcode options but with dots replaced with underscores. If the API is specified in the configuration _and_ the shortcode options, the latter takes precedence. |
|