styling docs

demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/GettingStarted.kt

@@ -0,0 +1,13 @@
+@file:Suppress("unused")
+
+package dev.sargunv.maplibrecompose.demoapp.docs
+
+import androidx.compose.runtime.Composable
+import dev.sargunv.maplibrecompose.compose.MaplibreMap
+
+// -8<- [start:app]
+@Composable
+fun MyApp() {
+  MaplibreMap()
+}
+// -8<- [end:simple-app]

demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/README.md

@@ -0,0 +1,3 @@
+The files in this package are not used by the demo app; they're just here to be
+included as snippets in the documentation. By including them in the demo app
+build, we can ensure that they're always up-to-date with the latest code.

demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/Styling.kt

@@ -0,0 +1,26 @@
+@file:Suppress("unused")
+
+package dev.sargunv.maplibrecompose.demoapp.docs
+
+import androidx.compose.foundation.isSystemInDarkTheme
+import androidx.compose.runtime.Composable
+import dev.sargunv.maplibrecompose.compose.MaplibreMap
+import dev.sargunv.maplibrecompose.demoapp.generated.Res
+import org.jetbrains.compose.resources.ExperimentalResourceApi
+
+@OptIn(ExperimentalResourceApi::class)
+@Composable
+fun Styling() {
+  // -8<- [start:simple]
+  MaplibreMap(styleUrl = "https://tiles.openfreemap.org/styles/liberty")
+  // -8<- [end:simple]
+
+  // -8<- [start:dynamic]
+  val variant = if (isSystemInDarkTheme()) "dark" else "light"
+  MaplibreMap(styleUrl = "https://api.protomaps.com/styles/v4/$variant/en.json?key=MY_KEY")
+  // -8<- [end:dynamic]
+
+  // -8<- [start:local]
+  MaplibreMap(styleUrl = Res.getUri("files/style.json"))
+  // -8<- [end:local]
+}

docs/docs/getting-started.md

@@ -73,10 +73,7 @@ cocoapods {
 In your Composable UI, add a map:
 
 ```kotlin title="App.kt"
-@Composable
-fun App() {
-  MaplibreMap()
-}
+-8<- "demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/GettingStarted.kt:app"
 ```
 
 When you run your app, you should see the default [demotiles] map. To learn how

docs/docs/styling.md

@@ -1 +1,47 @@
 # Styling
+
+## Acquiring a style
+
+Every MapLibre map requires a style to be displayed. The style is a JSON object
+that describes what data to display and how to display it. Typically, vector
+tile providers create styles designed to work with their data, and provide them
+as a URL. You can also create your own styles using [Maputnik][maputnik], a
+visual style editor for MapLibre styles.
+
+There are a variety of free and commercial map tile providers available. See the
+[awesome-maplibre][awesome-maplibre] repository for a list of tile providers.
+This documentation primarily uses OpenFreeMap and Protomaps. Both of these are
+free tile providers with their own styles.
+
+## Using a style
+
+To use a style, you can pass the `styleUrl` of the style to the `MaplibreMap`
+composable:
+
+```kotlin
+-8<- "demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/Styling.kt:simple"
+```
+
+## Dark mode
+
+You can select a style at runtime based on regular Compose logic. MapLibre will
+automatically animate the transition between styles:
+
+```kotlin
+-8<- "demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/Styling.kt:dynamic"
+```
+
+## Local styles
+
+While styles are typically hosted on the internet, you can also load a style
+from a Compose resource URI:
+
+```kotlin
+-8<- "demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/Styling.kt:local"
+```
+
+[maputnik]: https://maputnik.github.io/
+[awesome-maplibre]:
+  https://github.com/maplibre/awesome-maplibre#maptile-providers
+[openfreemap]: https://openfreemap.org/
+[protomaps]: https://protomaps.com/

docs/mkdocs.yml

@@ -65,7 +65,9 @@ markdown_extensions:
   - pymdownx.keys
   - pymdownx.mark
   - pymdownx.smartsymbols
-  - pymdownx.snippets
+  - pymdownx.snippets:
+      base_path: ../
+      dedent_subsections: true
   - pymdownx.superfences
   - pymdownx.tabbed:
       alternate_style: true