Merge pull request #158 from GeotrekCE/mfu-improve-doc-and-readme

docs: improve readme and settup documentation page
GeotrekCE · Nov 14, 2024 · e6ce310 · e6ce310
2 parents f0ee4e7 + dcdf34d
commit e6ce310
Show file tree

Hide file tree

Showing 5 changed files with 109 additions and 55 deletions.
diff --git a/docs/documentation/introduction/get-started.md b/docs/documentation/introduction/get-started.md
@@ -1,45 +1,53 @@
-# Installation
+# Installation du widget
 
-## Configuration dans le Storybook
+## Configuration dans Storybook
 
-Le widget peut être facilement testé et configuré à l'aide d'un outil de construction appelé [**Storybook**](https://geotrekce.github.io/Geotrek-rando-widget/?path=/story/geotrek-rando-widget--app). Il se base sur les identifiants d'objets dans Geotrek-admin, permet d'appliquer des filtres potentiels et d'ajuster le style selon les besoins.
+Vous pouvez tester et configurer le widget Geotrek-Rando dans un outil interactif appelé [**Storybook**](https://geotrekce.github.io/Geotrek-rando-widget/?path=/story/geotrek-rando-widget--app). 
 
-Voici les différentes étapes à suivre :
+Dans Storybook, vous pouvez personnaliser l’apparence et le comportement du widget avant de l’intégrer à votre site web. Storybook se base sur les identifiants d'objets dans Geotrek-admin, permet d'appliquer des filtres potentiels et d'ajuster le style selon les besoins.
 
-1. L'API doit au préalable autoriser les requêtes issues de `geotrekce.github.io`
+### Étapes à suivre
 
-2. Adapter le code du widget dans le Storybook en éditant les controls : changer le fond de plan cartographique, les couleurs, la langue, l'attribution, l'API, les paramètres de requête
+1. **Vérifiez l'accès à l'API**  
+   Avant de commencer, assurez-vous que l’API de votre Geotrek-admin autorise les requêtes provenant de `geotrekce.github.io`.
 
-3. Se rendre sur l'onglet Docs puis cliquer sur Show code pour afficher le code source qu'il vous faudra inclure dans votre site Web
+2. **Personnalisez le widget**  
+   Dans Storybook, utilisez les options de configuration (appelées "controls") pour :
+   - Modifier le fond de plan (carte de base)
+   - Changer les couleurs, la langue, et les informations d’attribution
+   - Configurer les paramètres d'API et les filtres (villes, secteurs, etc.)
+
+3. **Générez le code**  
+   Allez dans l'onglet "Docs" de Storybook et cliquez sur **Show code** pour obtenir le code HTML. Vous l'intégrerez ensuite dans votre site.
 
 <center>
   <a title="Storybook"><img src="/introduction/storybook.jpg" alt="Storybook"></a>
 </center>
 
- ::: tip
-- Dans les champs filtre (cities, districts, structures, themes, portals, etc.) il faut indiquer les identifiants des objets et non leur nom.
-- Pour connaître le lien entre identifiant et nom des objets, il est possible d'utiliser l'api (exemple pour lister l'ensemble des secteurs : https://randoadmin.parc-haut-jura.fr/api/v2/district/)
-- Il faut que l'itinéraire soit publié sur Geotrek-admin pour apparaître sur Geotrek-rando-widget
-
+::: tip Astuces
+- Pour les champs de filtre (villes, secteurs, structures, etc.), utilisez les identifiants des objets, pas leur nom.
+- Vous pouvez consulter l’API pour obtenir les identifiants (exemple pour les secteurs : https://randoadmin.parc-haut-jura.fr/api/v2/district/).
+- Assurez-vous que l'itinéraire est publié dans Geotrek-admin pour qu'il apparaisse dans le widget.
 :::
 
-## Intégration sur un site internet
-
-1. L'API doit au préalable autoriser n'importe qui à accéder aux données ou autoriser explicitement un nom de domaine
-
-2. Copier-coller ces balises HTML dans la section <head></head> du site web
+## Intégration sur votre site web
 
-```html
-<link rel="stylesheet" href="https://rando-widget.geotrek.fr/latest/dist/geotrek-rando-widget/geotrek-rando-widget.css" />
-<script type="module" src="https://rando-widget.geotrek.fr/latest/dist/geotrek-rando-widget/geotrek-rando-widget.esm.js"></script>
-<script nomodule src="https://rando-widget.geotrek.fr/latest/dist/geotrek-rando-widget/geotrek-rando-widget.js"></script>
-```
+1. **Autorisez l'accès à l'API**  
+   L’API de Geotrek-admin doit être configurée pour autoriser l’accès aux données soit à tout le monde, soit spécifiquement au domaine de votre site.
 
- ::: tip
-  - Utiliser le tag `latest` permet de bénéficier de la dernière version à jour du widget. 
+2. **Ajoutez le widget dans la section `<head>` de votre site**  
+   Copiez et collez les balises HTML ci-dessous dans la section `<head>` de votre site web
 
-  - Il peut cependant être préférable d'indiquer le numéro de la version (exemple : `https://rando-widget.geotrek.fr/0.13.0/dist/geotrek-rando-widget/geotrek-rando-widget.css`) plutôt que `latest` afin de figer une version précise du widget en production pour conserver un comportement stable et éviter les breaking changes.
+   ```html
+   <link rel="stylesheet" href="https://rando-widget.geotrek.fr/latest/dist/geotrek-rando-widget/geotrek-rando-widget.css" />
+   <script type="module" src="https://rando-widget.geotrek.fr/latest/dist/geotrek-rando-widget/geotrek-rando-widget.esm.js"></script>
+   <script nomodule src="https://rando-widget.geotrek.fr/latest/dist/geotrek-rando-widget/geotrek-rando-widget.js"></script>
+   ```
 
+::: tip Conseil de version
+   - Le tag `latest` garantit que vous utiliserez toujours la version la plus récente du widget.
+   - Si vous souhaitez figer une version spécifique (ex. : `https://rando-widget.geotrek.fr/0.13.0/...`), remplacez `latest` par le numéro de version pour conserver un comportement stable et éviter les breaking changes.
 :::
 
-3. Insérer le code source du widget généré à la dernière étape de la section précédente, dans la section du site Web dans laquelle il devra s'afficher
+3. **Insérez le code généré**  
+   Collez le code source du widget généré depuis Storybook dans la section de votre site où vous souhaitez afficher le widget.
diff --git a/docs/public/assets/demo.jpg b/docs/public/assets/demo.jpg
diff --git a/docs/public/assets/examples.jpg b/docs/public/assets/examples.jpg
diff --git a/docs/public/assets/geotrek-widget.png b/docs/public/assets/geotrek-widget.png
diff --git a/readme.md b/readme.md
@@ -1,46 +1,92 @@
-# Geotrek-rando widget
+<h1 align="center">Geotrek-rando-widget</h1>
 
-Web components of [Geotrek](https://geotrek.fr/).\
-You can use a complete app or each component independantly.
+<p align="center"><img alt="geotrek widget image" src="/docs/public/assets/geotrek-widget.png"></p>
 
-- To test and configure the widget: https://geotrekce.github.io/Geotrek-rando-widget/
-- Examples:
-  - https://www.jurabsolu.fr/decouvrez-territoire-jura/randonnees-forets-vignes-jura/
-  - https://www.coeurdujura-tourisme.com/activites-nature-jura-outdoor-loisirs/activites-pleine-nature/
-  - https://geotrek.ecrins-parcnational.fr/ressources/technique/2022-test-widget.html
+<p align="center">
+<a href="https://geotrek-rando-widget.readthedocs.io/stable/documentation/introduction/overview.html" rel="nofollow"><img alt="Documentation" src="https://img.shields.io/badge/Documentation-green.svg" style="max-width:100%;"></a>
+<a href="https://demo-rando-widget.geotrek.fr/" rel="nofollow"><img alt="Geotrek Widget demo" src="https://img.shields.io/badge/Demo-purple.svg" style="max-width:100%;"></a>
+<a href="https://matrix.to/#/%23geotrek:matrix.org" rel="nofollow"><img alt="Chat Matrix" src="https://img.shields.io/badge/Chat-blue.svg" style="max-width:100%;"></a>
+<a href="https://groups.google.com/g/geotrek-fr" rel="nofollow"><img alt="Forum Google Group" src="https://img.shields.io/badge/Forum-brightgreen.svg" style="max-width:100%;"></a>
+<a href="https://github.com/GeotrekCE/Geotrek-rando-widget/releases/latest" rel="nofollow"><img alt="Release" src="https://img.shields.io/github/release/GeotrekCE/Geotrek-rando-widget.svg" style="max-width:100%;"></a>
+</p>
 
-## Usage
+<p align="center">
+    <a href="#widget"><b>Widget</b></a>  •  
+    <a href="#features"><b>Features</b></a>  • 
+    <a href="#test-and-configure-the-widget"><b>Configuration</b></a>  • 
+    <a href="#documentation"><b>Documentation</b></a>  •      
+</p>
+<p align="center">  
+    <a href="#support"><b>Support</b></a>  •   
+    <a href="#contribution"><b>Contribution</b></a>  •  
+    <a href="#thanks-to-all-contributors-"><b>Contributors</b></a>  •  
+    <a href="#license"><b>License</b></a>  • 
+</p>
 
-**The Geotrek-admin API you want to use has to authorize the URL of the website where you want to include the widget.**
+![Search](/docs/public/assets/demo.jpg)
 
-Copy-paste this inside `<head></head>` to load static widget files:
+## Widget
 
-```html
-<link rel="stylesheet" href="https://rando-widget.geotrek.fr/latest/dist/geotrek-rando-widget/geotrek-rando-widget.css" />
-<script type="module" src="https://rando-widget.geotrek.fr/latest/dist/geotrek-rando-widget/geotrek-rando-widget.esm.js"></script>
-<script nomodule src="https://rando-widget.geotrek.fr/latest/dist/geotrek-rando-widget/geotrek-rando-widget.js"></script>
-```
+**Geotrek-rando-widget** is an intuitive module in the Geotrek suite designed for embedding interactive geographic content on any website. Perfect for tourist offices, natural parks, and organizations promoting a territory, the widget is as simple to embed as a YouTube video.
 
-Then you have to configure the widget to generate the widget code to include in your website.
+Geotrek Rando Widget provides a flexible, lightweight solution for integrating [Geotrek-admin](https://github.com/GeotrekCE/Geotrek-admin) data on your website without needing a dedicated platform like [Geotrek-rando](https://github.com/GeotrekCE/Geotrek-rando-v3).
 
-## Configure
+### Test and configure the widget
 
-**The API you want to use has to authorize geotrekce.github.io.**
+Explore the widget and its configuration options here: [Geotrek-rando-widget Storybook](https://geotrekce.github.io/Geotrek-rando-widget/)
 
-You can explore Geotrek-rando widget and create your own component [here](https://geotrekce.github.io/Geotrek-rando-widget/).\
-Once you made your component, you can get the code to copy-paste by clicking on _Docs_ then _Show code_.
+### Examples of Geotrek-widget's integration
 
-<a href="https://territoires.makina-corpus.com/"><img src="https://geotrek.fr/assets/img/logo_makina.svg" alt="Logo MCT" width="115"></a>
-[![](https://geotrek.fr/assets/img/logo_autonomens-h120m.png)](https://datatheca.com/)
+- [Walks and Hikes in Sidobre & Valleys, Tarn](https://sidobre-vallees-tourisme.com/type_activite/balades-et-randonnees-sidobre-vallees/)
+- [Hiking in Haut Jura Saint-Claude](https://www.haut-jura-saint-claude.com/pause-aventure/randonnee-haut-jura/)
+- [Cycling Trails in Coeur du Jura](https://www.coeurdujura-tourisme.com/parcours-randonnees-velo/)
+- [Walks and Hikes in Occitanie](https://www.la-toscane-occitane.com/a-voir-a-faire/balades-randonnees)
+
+![Examples](/docs/public/assets/examples.jpg)
+
+## Features
+
+With a mobile-responsive design, multilingual support, and customizable components, **Geotrek-rando-widget** enables websites to dynamically present treks, activities, services, and events, complete with multilingual support, advanced filtering, and detailed information pages—all easily customizable to suit any site’s needs. Key features include:
+
+- **Web component**: geotrek-rando-widget is a web component that can be easily embedded on any website.
+- **Responsive design**: it adapts to different screen sizes, providing an optimal display on desktop, tablet, and mobile devices.
+- **Geotrek-admin API v2**: retrieves data in real-time via the Geotrek-admin API.
+- **Flexible configuration**: easily customizable and integrable into any website.
+- **Multi-language support**: displays content in multiple languages (e.g. english, spanish) if translations are available in Geotrek-admin.
+- **Advanced filtering and search**: allows users to filter and search objects in a list view with precision.
+- **Detailed list view**: shows published objects (treks, services, tourist events, etc.) with a main photo, name, and key features (difficulty, distance, elevation gain).
+- **Detailed object page**: provides a complete view of an object with all textual details (POI, sensitive areas, recommendations, etc.) configured in Geotrek-admin.
+- **Download options**: users can download GPX/KML route files and a PDF version of the detailed page.
+- **Easy sharing**: users can copy and share the URL of a detailed object page.
 
 ## Documentation
 
-- [Presentation](https://geotrek-rando-widget.readthedocs.io/latest/documentation/introduction/overview.html)
-- [Get started](https://geotrek-rando-widget.readthedocs.io/latest/documentation/introduction/get-started.html)
-- [Theme](https://geotrek-rando-widget.readthedocs.io/latest/documentation/theme/colors.html)
+For detailed setup and examples, visit the documentation:
+- [Overview](https://geotrek-rando-widget.readthedocs.io/stable/documentation/introduction/overview.html)
+- [Get started](https://geotrek-rando-widget.readthedocs.io/stable/documentation/introduction/get-started.html)
+
+## Support
+
+Have questions or feedback? Connect with our community:
+- Report issues or suggest features by [submitting a ticket](https://github.com/GeotrekCE/Geotrek-rando-widget/issues).
+- Join discussions on [Matrix](https://matrix.to/#/%23geotrek:matrix.org) or exchange insights in our [Google Group](https://groups.google.com/g/geotrek-fr).
 
 ## Contribution
 
-- [Development guide](https://geotrek-rando-widget.readthedocs.io/latest/documentation/contribution/development.html)
-- [Documentation guide](https://geotrek-rando-widget.readthedocs.io/latest/documentation/contribution/documentation.html)
-- [Translating guide](https://geotrek-rando-widget.readthedocs.io/latest/documentation/contribution/translation.html)
+Interested in contributing? Check out our [Contributing Guide](https://geotrek-rando-widget.readthedocs.io/stable/documentation/contribution/development.html). All types of contributions are welcome—even if you’re not a coder!
+
+## Thanks to all contributors ❤
+
+<a href="https://github.com/GeotrekCE/Geotrek-rando-widget/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=GeotrekCE/Geotrek-rando-widget" />
+</a>
+
+Made with [contrib.rocks](https://contrib.rocks).
+
+## License
+
+This project is under the MIT License. See the [LICENSE](https://github.com/GeotrekCE/Geotrek-rando-widget/blob/main/LICENSE) for details.
+
+<a href="https://territoires.makina-corpus.com/"><img src="https://geotrek.fr/assets/img/logo_makina.svg" alt="Logo MCT" width="115"></a>
+[![](https://geotrek.fr/assets/img/logo_autonomens-h120m.png)](https://datatheca.com/)
+