From 549d8c67e74c5a2d440b093fcd788a28ddbe9f38 Mon Sep 17 00:00:00 2001
From: imperosol <thgirod@hotmail.com>
Date: Thu, 3 Sep 2026 15:00:02 +0200
Subject: [PATCH] doc: ae markdown

---
 docs/tutorial/markdown.md | 51 +++++++++++++++++++++++++++++++++++++++
 mkdocs.yml                |  1 +
 2 files changed, 52 insertions(+)
 create mode 100644 docs/tutorial/markdown.md

diff --git a/docs/tutorial/markdown.md b/docs/tutorial/markdown.md
new file mode 100644
index 00000000..319b2f43
--- /dev/null
+++ b/docs/tutorial/markdown.md
@@ -0,0 +1,51 @@
+## syntaxe aemark
+
+Le site AE utilise markdown pour le rendu de la plupart
+des textes saisis par les utilisateurs.
+Cependant, la syntaxe utilisée n'est pas celle officielle
+telle que définie par John Gruber,
+mais est basée sur [CommonMark](https://commonmark.org/),
+avec quelques variations pour les usages particuliers du site AE.
+
+Les deux principaux ajouts sont :
+
+- Les urls commençant par `page://` sont modifiées pour commencer par `/page/`
+- Des modificateurs de taille peuvent être indiqués directement dans la source
+  d'une image
+
+Les variations d'aemark sont documentées sur
+[le site AE](https://ae.utbm.fr/page/Aide_sur_la_syntaxe/).
+
+Le code est hébergé sur le dépôt Git [aemark](https://github.com/ae-utbm/ae-markdown).
+
+## Utiliser aemark
+
+Le code du parser aemark est écrit en Rust dans une librairie
+indépendante, avec des bindings vers différents langages.
+Les librairies mises à disposition exposent une seule fonction,
+qui prend simplement du markdown en entrée et renvoie l'HTML correspondant.
+
+Les librairies pour les différents langages sont toutes
+basées sur le même code Rust.
+La seule différence entre chacune tient uniquement dans la manière
+d'intégrer ce code dans les bindings.
+De cette manière, le comportement est assuré d'être le même
+sur toutes les plateformes disponibles, avec en prime des performances
+respectables.
+
+
+=== ":simple-python: Python"
+
+    ```python
+    from aemark import markdown
+
+    result = markdown("this is some *markdown text* with __formatting__")
+    ```
+
+=== ":simple-javascript: Javascript"
+
+    ```typescript
+    import { markdown } from "@ae_utbm/aemark"
+
+    const result = markdown("this is some *markdown text* with __formatting__");
+    ```
diff --git a/mkdocs.yml b/mkdocs.yml
index cd6df0de..48a966f5 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -71,6 +71,7 @@ nav:
     - API:
       - Développement: tutorial/api/dev.md
       - Connexion à l'API: tutorial/api/connect.md
+    - Markdown AE: tutorial/markdown.md
     - Etransactions: tutorial/etransaction.md
   - How-to:
     - L'ORM de Django: howto/querysets.md