docs: add docusaurus

.github/workflows/build-deploy-docs.yml

@@ -0,0 +1,34 @@
+name: Generate documentation
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    defaults:
+      run:
+        working-directory: docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        # Can't use cache because build fails with "Dependencies lock file is not found"
+        # with:
+        #  cache: yarn
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile --non-interactive
+      - name: Build
+        run: yarn build
+      - name: Deploy to GitHub Pages
+        if: github.repository_owner == 'maplibre'
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/build
+          keep_files: true

.github/workflows/build-docs.yml

@@ -0,0 +1,22 @@
+name: Generate documentation
+
+on: [ push, pull_request, workflow_dispatch ]
+
+jobs:
+  build:
+    defaults:
+      run:
+        working-directory: docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        # Can't use cache because build fails with "Dependencies lock file is not found"
+        # with:
+        #  cache: yarn
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile --non-interactive
+      - name: Build
+        run: yarn build

.github/workflows/dependency-review.yml

@@ -17,4 +17,4 @@ jobs:
       - name: 'Checkout Repository'
         uses: actions/checkout@v4
       - name: 'Dependency Review'
-        uses: actions/dependency-review-action@v4
+        uses: actions/dependency-review-action@v4.3.3

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,49 @@
+# Documentation
+
+The documentation website is built using [Docusaurus](https://docusaurus.io/), 
+a static website generator.
+See the hosted documentation at [TODO insert url]()
+
+## Run locally
+
+To run the website locally, you need to have Node.js and yarn installed. 
+You can Node.js from [here](https://nodejs.org/) and install yarn by running 
+`npm install -g yarn`.
+
+Run the following commands to fetch the dependencies:
+
+```bash
+yarn
+```
+
+Then, run the following command to start the development server:
+
+```bash
+yarn start
+```
+
+This command starts a local development server. Most changes are reflected live 
+without having to restart the server.
+
+### Create new docs version
+
+To create a new version of the documentation, run the following command:
+
+```bash
+yarn docusaurus docs:version <version>
+```
+
+A new `versioned_docs.version-<version>` folder will be created and the version
+gets added to the `versions.json` file.
+
+### Build
+
+```bash
+yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+The website is deployed automatically to GitHub Pages via CI.

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/docs/faq.md

@@ -0,0 +1,48 @@
+---
+sidebar_position: 5
+---
+
+# FAQ
+
+### Loading .mbtiles tile files or sprites/glyphs from the assets shipped with the app
+
+One approach that has been used successfully to do that is to copy the files
+from the app's assets directory to another directory, e.g. the app's cache
+directory, and then reference that location.
+See e.g. issues https://github.com/maplibre/flutter-maplibre-gl/issues/338
+and https://github.com/maplibre/flutter-maplibre-gl/issues/318
+
+### Avoid Android UnsatisfiedLinkError
+
+Update buildTypes in `android\app\build.gradle`
+
+```gradle title="android\app\build.gradle"
+buildTypes {
+    release {
+        // other configs
+        ndk {
+            abiFilters 'armeabi-v7a','arm64-v8a','x86_64', 'x86'
+        }
+    }
+}
+```
+
+### Layer is not displayed on IOS, but no error
+
+Have a look in your `LayerProperties` object, if you supply a `lineColor`
+argument, (or any color argument) the issue might come from here.
+Android supports the following format : `'rgba(192, 192, 255, 1.0)'`, but on
+iOS, this doesn't work!
+
+You have to have the color in the following format : `#C0C0FF`
+
+### iOS crashes with error: `'NSInvalidArgumentException', reason: 'Invalid filter value: filter property must be a string'`
+
+Check if one of your expression is : `["!has", "value"]`. Android support this
+format, but iOS does not.
+You can replace your expression with :   `["!",["has", "value"] ]` which works
+both in Android and iOS.
+
+Note : iOS will display the
+error : `NSPredicate: Use of 'mgl_does:have:' as an NSExpression function is forbidden`,
+but it seems like the expression still works well.

docs/docs/features/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Features",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "description": "Dive in to the features MapLibre GL for Flutter provides."
+  }
+}

docs/docs/features/supported-features.md

@@ -0,0 +1,18 @@
+---
+sidebar_position: 1
+---
+
+# Supported Features
+
+| Feature        | Android | iOS | Web | Windows | MacOS | Linux |
+|----------------|:-------:|:---:|:---:|:-------:|:-----:|:-----:|
+| Style          |    ✅    |  ✅  |  ✅  |    ❌    |   ❌   |   ❌   |
+| Camera         |    ✅    |  ✅  |  ✅  |    ❌    |   ❌   |   ❌   |
+| Gesture        |    ✅    |  ✅  |  ✅  |    ❌    |   ❌   |   ❌   |
+| User Location  |    ✅    |  ✅  |  ✅  |    ❌    |   ❌   |   ❌   |
+| Symbol         |    ✅    |  ✅  |  ✅  |    ❌    |   ❌   |   ❌   |
+| Circle         |    ✅    |  ✅  |  ✅  |    ❌    |   ❌   |   ❌   |
+| Line           |    ✅    |  ✅  |  ✅  |    ❌    |   ❌   |   ❌   |
+| Fill           |    ✅    |  ✅  |  ✅  |    ❌    |   ❌   |   ❌   |
+| Fill Extrusion |    ✅    |  ✅  |  ✅  |    ❌    |   ❌   |   ❌   |
+| Heatmap Layer  |    ✅    |  ✅  |  ✅  |    ❌    |   ❌   |   ❌   |

docs/docs/getting-started/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Getting Started",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "Quick start guide"
+  }
+}

docs/docs/getting-started/add-dependency.md

@@ -0,0 +1,24 @@
+---
+sidebar_position: 1
+---
+
+# Add Dependency
+
+Add `maplibre_gl` to your project by running this command:
+
+```bash
+flutter pub add maplibre_gl
+```
+
+or add it directly as a dependency to your `pubspec.yaml` file and run 
+`flutter pub get`:
+
+```yaml title="pubspec.yaml"
+dependencies:
+  maplibre_gl: ^0.20.0 # use the latest version found on pub.dev
+```
+
+You can find the latest version of the package on
+[pub.dev](https://pub.dev/packages/maplibre_gl) or here:
+
+[![Pub Version](https://img.shields.io/pub/v/maplibre_gl)](https://pub.dev/packages/maplibre_gl)

docs/docs/getting-started/setup-android.md

@@ -0,0 +1,72 @@
+---
+sidebar_position: 3
+---
+
+# Setup Android
+
+## Use a compatible Kotlin version
+
+Ensure that you are using Kotlin version
+**1.9.0** or newer. You can check the most recent Kotlin version on
+[kotlinlang.org](https://kotlinlang.org/docs/releases.html#release-details).
+
+#### (new) Gradle with a declarative plugins block
+
+Open `android/settings.gradle` and set the Kotlin version like this:
+
+```gradle title="android/settings.gradle"
+plugins {
+    // ...
+    id "org.jetbrains.kotlin.android" version "1.9.0" apply false
+}
+```
+
+In case you can't find the `plugins {}` block your app still uses the old apply
+script method.
+
+#### (old) In a legacy apply script gradle file:
+
+Open `android/app/build.gradle` and set the Kotlin version like this:
+
+```gradle title="android/app/build.gradle"
+buildscript {
+    ext.kotlin_version = '1.9.0'
+    // ...
+}
+```
+
+## Minimum SDK version
+
+If you are using a flutter version below 3.22, you need to set the minimum SDK
+version to 21 or higher in `android/app/build.gradle`.
+
+```gradle title="android/app/build.gradle"
+    defaultConfig {
+        minSdk = 21 // previously flutter.minSdkVersion
+        // ...
+    }
+```
+
+If you are using the old apply script method in gradle, `minSdk` is named
+`minSdkVersion`.
+
+Starting from flutter 3.22, the minimum SDK version is set to 21 by default
+and you can keep `flutter.minSdkVersion`.
+
+## Use the location feature
+
+If you want to show the user's location on the map you need to add
+the `ACCESS_COARSE_LOCATION` or `ACCESS_FINE_LOCATION` permission in the
+application manifest `android/app/src/main/AndroidManifest.xml`.
+
+```xml title="android/app/src/main/AndroidManifest.xml"
+
+<manifest>
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
+    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
+</manifest>
+```
+
+Starting from Android API level 23 you also need to request it at runtime. This
+plugin does not handle this for you. Our example app uses the
+[flutter plugin "location"](https://pub.dev/packages/location) for this.

docs/docs/getting-started/setup-ios.md

@@ -0,0 +1,41 @@
+---
+sidebar_position: 2
+---
+
+# Setup iOS
+
+There is no longer any specific setup needed to include the package on iOS.
+
+## Use the location feature
+
+If you access your users' location, you should also add the following key
+to `ios/Runner/Info.plist` to explain why you need access to their location
+data:
+
+```xml title="ios/Runner/Info.plist"
+<dict>
+    <key>NSLocationWhenInUseUsageDescription</key>
+    <string>[Your explanation here]</string>
+</dict>
+```
+
+A possible explanation could be: "Shows your location on the map".
+
+## Upgrading from a previous version
+
+Previous versions of the package required you to add the following lines to
+your `ios/Podfile`. You'll have to remove these lines from your `ios/Podfile` 
+or your project won't build.
+
+<details>
+<summary>View obsolete code</summary>
+
+```ruby title="ios/Podfile"
+source 'https://cdn.cocoapods.org/'
+source 'https://github.com/m0nac0/flutter-maplibre-podspecs.git'
+
+pod 'MapLibre'
+pod 'MapLibreAnnotationExtension'
+```
+
+</details>

docs/docs/getting-started/setup-web.md

@@ -0,0 +1,26 @@
+---
+sidebar_position: 4
+---
+
+# Setup Web
+
+Include the following JavaScript and CSS files in the `<head>` tag of
+your `web/index.html` file:
+
+```html title="web/index.html"
+<!DOCTYPE html>
+<html>
+<head>
+    <!-- other html -->
+
+    <!-- MapLibre -->
+    <script src='https://unpkg.com/maplibre-gl@^4.3/dist/maplibre-gl.js'></script>
+    <link href='https://unpkg.com/maplibre-gl@^4.3/dist/maplibre-gl.css'
+          rel='stylesheet'/>
+</head>
+</html>
+```
+
+`^4.3` ensures that your app will always use the latest version of
+[maplibre-gl-js](https://github.com/maplibre/maplibre-gl-js) v4 but not suddenly
+use an incompatible version.