Merge branch 'docs'

.github/workflows/deploy.yml

@@ -0,0 +1,51 @@
+name: Deploy VitePress site to Pages
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: yarn
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Install dependencies
+        run: yarn install --immutable
+      - name: Build with VitePress
+        run: yarn docs:build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,5 +1,6 @@
 node_modules/
 /dist/
+/docs/.vitepress/cache
 
 .yarn/*
 !.yarn/patches

docs/.vitepress/config.ts

@@ -0,0 +1,48 @@
+import { defineConfig } from 'vitepress'
+import examplesPath from '../examples/[example].paths.js';
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "vue-maplibre-gl",
+  description: "Vue 3 plugin for maplibre-gl",
+  transformPageData: (pageData, { siteConfig }) => {
+    if (pageData.filePath.startsWith('examples/') && pageData.filePath != 'examples/index.md') {
+      return {
+        title: `${pageData.params.title} - Examples`
+      }
+    }
+  },
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Guide', link: '/guide/installation' },
+      { text: 'Examples', link: '/examples/' },
+      { text: 'API', link: '/api/' }
+    ],
+
+    sidebar: [
+      {
+        text: 'Guide',
+        items: [
+          { text: 'Installation', link: '/guide/installation' },
+          { text: 'Getting started', link: '/guide/getting-started' }
+        ]
+      },
+      {
+        text: 'Examples',
+        link: '/examples/',
+        items: examplesPath.paths().map((example) => {
+          return {
+            text: example.params.title,
+            link: `/examples/${example.params.example}`
+          };
+        })
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/indoorequal/vue-maplibre-gl' }
+    ]
+  }
+})

docs/api/index.md

@@ -0,0 +1,3 @@
+# API
+
+Coming soon ...

docs/examples/[example].md

@@ -0,0 +1,5 @@
+# {{ $params.title }}
+
+{{ $params.description }}
+
+<!-- @content -->

docs/examples/[example].paths.js

@@ -0,0 +1,13 @@
+import fs from 'node:fs';
+import path from 'path';
+import examplesData from './example.data.js';
+
+export default {
+  paths() {
+    const examplesFolder = path.join('./docs/examples');
+    const files = fs.readdirSync(examplesFolder)
+          .filter(f => f.endsWith('vue'))
+          .map(f => examplesFolder + '/' + f);
+    return examplesData.load(files);
+  }
+}

docs/examples/basic.vue

@@ -0,0 +1,33 @@
+// Basic
+//
+// A basic map with a style and controls
+<template>
+  <mgl-map
+    :map-style="style"
+    :center="center"
+    :zoom="zoom"
+  >
+    <mgl-navigation-control />
+  </mgl-map>
+</template>
+
+<script setup>
+import {
+  MglMap,
+  MglNavigationControl,
+} from 'vue-maplibre-gl';
+
+const style = 'https://api.maptiler.com/maps/streets/style.json?key=cQX2iET1gmOW38bedbUh';
+const center = [12.550343, 55.665957];
+const zoom = 8;
+</script>
+
+<style lang="scss">
+@import "maplibre-gl/dist/maplibre-gl.css";
+@import "vue-maplibre-gl/dist/vue-maplibre-gl.css";
+
+body {
+  margin: 0;
+}
+html, body, #app { height: 100%; }
+</style>

docs/examples/example.data.js

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+function removeComment(str) {
+  return str.replace(/^\/\/ /, '');
+}
+
+export default {
+  watch: ['./*.vue'],
+  load(watchedFiles) {
+    return watchedFiles.map((file) => {
+      const vueContent = fs.readFileSync(file, 'utf-8').split('\n');
+      const title = removeComment(vueContent[0]);
+      const description = removeComment(vueContent[2]);
+      const content = `
+<script setup>
+import Example from './${path.basename(file)}';
+</script>
+<Example style="height: 500px" />
+\`\`\`vue
+${vueContent.slice(3).join('\n')}
+\`\`\`
+`;
+      return {
+        params: {
+          example: path.basename(file, '.vue'),
+          title,
+          description,
+        },
+        content,
+      };
+    });
+  }
+}

docs/examples/index.md

@@ -0,0 +1,14 @@
+<script setup>
+import { data } from './example.data.js'
+</script>
+
+# Examples
+
+Discover the examples.
+
+<ul>
+  <li v-for="example of data">
+    <a :href="`/examples/${example.params.example}`">{{ example.params.title }}</a>:
+    {{ example.params.description }}
+  </li>
+</ul>

docs/examples/marker.vue

@@ -0,0 +1,36 @@
+// Marker
+//
+// A map with a marker
+<template>
+  <mgl-map
+    :map-style="style"
+    :center="center"
+    :zoom="zoom"
+  >
+    <mgl-navigation-control />
+    <mgl-marker :coordinates="coordinates" color="#cc0000" />
+  </mgl-map>
+</template>
+
+<script setup>
+import {
+  MglMap,
+  MglNavigationControl,
+  MglMarker
+} from 'vue-maplibre-gl';
+
+const style = 'https://api.maptiler.com/maps/streets/style.json?key=cQX2iET1gmOW38bedbUh';
+const center = [12.550343, 55.665957];
+const zoom = 8;
+const coordinates = [12.550343, 55.665957];
+</script>
+
+<style lang="scss">
+@import "maplibre-gl/dist/maplibre-gl.css";
+@import "vue-maplibre-gl/dist/vue-maplibre-gl.css";
+
+body {
+  margin: 0;
+}
+html, body, #app { height: 100%; }
+</style>

docs/guide/getting-started.md

@@ -0,0 +1,37 @@
+# Getting started
+
+```typescript
+import VueMaplibreGl from 'vue-maplibre-gl'
+
+app.use(VueMaplibreGl)
+```
+
+Add CSS:
+
+```scss
+@import "~maplibre-gl/dist/maplibre-gl.css";
+@import "~vue-maplibre-gl/dist/vue-maplibre-gl.css";
+```
+
+Use specific components:
+
+```typescript
+import { MglMap } from 'vue-maplibre-gl'
+
+app.component('MglMap', MglMap)
+```
+
+or in a parent components `.vue` file
+
+```html
+<script>
+  import { MglMap } from 'vue-maplibre-gl'
+
+  export default {
+    components: {
+      MglMap
+    },
+    // ...
+  }
+</script>
+```

docs/guide/installation.md

@@ -0,0 +1,25 @@
+# Installation
+
+## Compatibility
+
+- Vue.js 3.x
+- maplibre-gl-js 3.x
+
+## Install
+
+
+::: code-group
+
+```sh [npm]
+npm install vue-maplibre-gl maplibre-gl mitt
+```
+
+```sh [yarn]
+yarn add vue-maplibre-gl maplibre-gl mitt
+```
+
+```sh [pnpm]
+pnpm add vue-maplibre-gl maplibre-gl mitt
+```
+
+:::

docs/index.md

@@ -0,0 +1,21 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "vue-maplibre-gl"
+  text: "Vue 3 plugin for maplibre-gl"
+  tagline:
+  actions:
+    - theme: brand
+      text: Examples
+      link: /examples/
+    - theme: alt
+      text: Guide
+      link: /guide/installation
+
+features:
+  - title: Support Maplibre-gl-js 3.x
+  - title: Vue 3 support
+  - title: Typescript support
+---

examples/basic.vue

@@ -0,0 +1,27 @@
+// Basic
+//
+// A basic map with a style and controls
+<template>
+  <mgl-map :map-style="style">
+    <mgl-navigation-control />
+  </mgl-map>
+</template>
+
+<script setup>
+import {
+  MglMap,
+  MglNavigationControl,
+} from 'vue-maplibre-gl';
+
+const style = 'https://api.maptiler.com/maps/streets/style.json?key=cQX2iET1gmOW38bedbUh';
+</script>
+
+<style lang="scss">
+@import "maplibre-gl/dist/maplibre-gl.css";
+@import "vue-maplibre-gl/dist/vue-maplibre-gl.css";
+
+body {
+  margin: 0;
+}
+html, body, #app { height: 100%; }
+</style>

package.json

@@ -37,7 +37,10 @@
   ],
   "scripts": {
     "build": "vue-tsc --noEmit && vite build",
-    "examples": "yarn workspace @indoorequal/vue-maplibre-gl-examples play"
+    "examples": "yarn workspace @indoorequal/vue-maplibre-gl-examples play",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "devDependencies": {
     "@babel/types": "^7.23.9",
@@ -54,7 +57,9 @@
     "vite": "^5.1.3",
     "vite-plugin-banner": "^0.7.1",
     "vite-plugin-dts": "^3.7.2",
+    "vitepress": "^1.1.3",
     "vue": "^3.4.19",
+    "vue-maplibre-gl": "workspace:^",
     "vue-tsc": "^2.0.0"
   },
   "peerDependencies": {