@trailstash/ultra/docs/style.md

A web based tool for making MapLibre GL maps with data from sources such as Overpass, GeoJSON, GPX, KML, TCX, etc

# Styling

[MapLibre styling](https://maplibe.org/maplibre-style-spec/) can be attached to a query
via the `style:` key of the [YAML front-matter](./yaml.md).

```
---
style: ... your MapLibre style here ...
---
... your query here ...
```

The value of the style: key can contain:

- a URL to a MapLibre style
- a full MapLibre style object
- a Ultra MapLibre style

## Ultra MapLibre styles

In order to simplify the use of MapLibre styles, Ultra implements a number of features.

### Query result styling

In order to allow for easy styling of the query results, Ultra allows you to specify a
style with only the layer for your query results.

For example, to render query results with a purple MapLibre
[circle](https://maplibre.org/maplibre-style-spec/layers/#circle) layer:

```
---
style:
  layers:
    - type: circle
      paint:
        circle-color: purple
---
nwr[shop]({{bbox}}); out center;
```

#### Extending a specific basemap style

To specify what style to add result styling to, use the `extends` key.

For example, to render the purple circles on the [Protomaps]() light basemap:

```
---
style:
  extends: https://styles.trailsta.sh/protomaps-light.json
  layers:
    - type: circle
      paint:
        circle-color: purple
---
nwr[shop]({{bbox}}); out center;
```

### Layer `source` & `id`

In the above examples, the layer definitions are lacking both source and layers keys.

Layers don't need to specify an ID, and if the source is not specified, it will be set to to the
source containting the query results.

### Automatic `paint` and `layer` keys

In order to reduce the mental overhead of remember what keys are
[`paint`](https://maplibre.org/maplibre-style-spec/layers/#paint) options and which are
[`layout`](https://maplibre.org/maplibre-style-spec/layers/#layout) options, Ultra will
automatically move them from the layer object into the appropriate options object.

For example, the above purple circle layer can be implemented as:

```
---
style:
  layers:
    - type: circle
      circle-color: purple
---
nwr[shop]({{bbox}}); out center;
```

### Sandwiching layers

In order to place your layers below existing style layers, you can use the `beforeLayerId:` key.

[Example](./Examples/bike-infra.md)

## sprites via HTTPS

In order to facilitate adding icons to the map that don't exist in the basemap's
[sprites](),
if `icon-image` is set to an HTTPS URL to an image, Ultra will automatically download
it and add it to the Map's images.

[Example](./MapLibre-Examples/add-image.md)

## Bundled Sprites

In order to simplify the creation of POI maps, Ultra bundles the
[Maki](https://github.com/mapbox/maki) and [Temaki](https://github.com/rapideditor/temaki) sprites
and adds them to your style as [SDFs](https://docs.mapbox.com/help/troubleshooting/using-recolorable-images-in-mapbox-maps/)
allowing for easy styling of icons.

Example:

```
---
style:
  layers:
    - type: symbol
      icon-image: maki:bus
      icon-color: white
      icon-halo-color: '#6486f5'
      icon-halo-width: 5
---
```

## Fallback fontstack

Since not all MapLibre styles have the same
[glyphs](https://maplibre.org/maplibre-style-spec/glyphs/), Ultra will default to using
Noto Sans Regular if the speficied(or default) fontstack is not available.