diff --git a/theming.md b/theming.md
new file mode 100644
index 00000000..4f44f7cb
--- /dev/null
+++ b/theming.md
@@ -0,0 +1,66 @@
+# Customize the appearance of the user portal
+
+## Using a theme
+
+Since YunoHost 3.5, you can change the theme of the user portal - though for now it requires tweaking via the command line.
+
+You can list the available themes with : 
+
+```bash
+$ ls /usr/share/ssowat/portal/assets/themes/
+```
+
+Then you can use `nano /etc/ssowat/conf.json.persistent` to enable the theme you choose like this :
+
+```json
+{
+    "theme": "light",
+    ...other lines...
+}
+```
+
+<div class="alert alert-info" markdown="1">
+You might need to force the refresh of your browser's cache for the theme to fully propagate. You can do so with Ctrl+Shift+R on Firefox.
+</div>
+
+## Adding someone else's theme
+
+You may add themes created by other people by downloading and extracting the corresponding files in a new folder `the_theme_name` in `/usr/share/ssowat/portal/assets/themes/`.
+
+<div class="alert alert-warning" markdown="1">
+**Beware** that adding third-party themes from random strangers on the internet **is a security risk**. It is equivalent to running someone's else code on your machine, which can be used for malicious purpose such as stealing credentials !
+</div>
+
+## Creating your own theme
+
+You can create your own theme by copying the existing theme of your choice. For instance starting from the light theme : 
+
+```bash
+cp -r /usr/share/ssowat/portal/assets/themes/{light,your_own_theme}
+```
+
+Then, edit the files the css and js files in `/usr/share/ssowat/portal/assets/themes/your_own_theme` according to what you want to do : 
+
+- `custom_portal.css` can be used to add custom CSS rules to the user portal ;
+- `custom_overlay.css` can be used to customize the small YunoHost button overlay, displayed on apps page which includes it ;
+- `custom_portal.js` can be used to add custom JS code to be ran both on the user portal or when injecting the small YunoHost button / overlay.
+
+You can also add your own images and assets which can then be used by the CSS and JS files.
+
+### Example : customizing the logo
+
+You may create your own theme simply to change the "branding" of the Yunohost user portal and replace the YunoHost logo with you own !
+
+To do so, upload your logo to `/usr/share/ssowat/portal/assets/themes/your_own_theme/`, and use the following CSS rules : 
+
+```css
+/* Inside custom_portal.css */
+#ynh-logo {
+  background-image: url("./your_logo.png");
+}
+
+/* Inside custom_overlay.css */
+#ynh-overlay-switch {
+  background-image: url("./your_logo.png");
+}
+```
diff --git a/theming_fr.md b/theming_fr.md
new file mode 100644
index 00000000..c915de0d
--- /dev/null
+++ b/theming_fr.md
@@ -0,0 +1,66 @@
+# Personnaliser l'apparence du portail utilisateur
+
+## Utiliser un thème
+
+Depuis YunoHost 3.5, il est possible de changer le thème du portail utilisateur - bien que pour l'instant il faille encore faire cette opération via la ligne de commande.
+
+Vous pouvez lister les thèmes disponibles avec : 
+
+```bash
+ls /usr/share/ssowat/portal/assets/themes/
+```
+
+Ensuite, vous pouvez utiliser `nano /etc/ssowat/conf.json.persistent` pour activer le thème que vous choisissez comme ceci :
+
+```json
+{
+    "theme" : "light",
+    ...autres lignes.....
+}
+```
+
+<div class="alert alert-info" markdown="1">
+Vous devrez peut-être forcer le rafraîchissement du cache de votre navigateur pour que le thème se propage complètement. Vous pouvez le faire avec Ctrl+Maj+R sur Firefox.
+</div> </div
+
+## Ajouter le thème de quelqu'un d'autre
+
+Vous pouvez ajouter des thèmes créés par d'autres personnes en téléchargeant et en extrayant les fichiers correspondants dans un nouveau dossier `nom_du_theme` dans `/usr/share/ssowat/portal/assets/themes/`.
+
+<div class="alert alert-warning" markdown="1">
+**Attention** : l'ajout de thèmes provenant d'inconnus sur Internet **est un risque de sécurité**. Cela équivaut à exécuter du code écrit par quelqu'un d'autre sur votre machine, et peut donc être utilisé à des fins malveillantes comme voler des mots de passe !
+</div> 
+
+## Créer votre propre thème
+
+Vous pouvez créer votre propre thème en copiant le thème existant de votre choix. Par exemple à partir du thème `light` : 
+
+```bash
+cp -r /usr/share/ssowat/portal/assets/themes/{light,votre_theme}
+```
+
+Ensuite, éditez les fichiers css et js dans `/usr/share/ssowat/portal/assets/themes/votre_theme` selon ce que vous voulez faire : 
+
+- `custom_portal.css` peut être utilisé pour ajouter des règles CSS personnalisées au portail utilisateur ;
+- `custom_overlay.css` peut être utilisé pour personnaliser le petit bouton YunoHost, présent sur les apps qui l'intègre ;
+- `custom_portal.js' peut être utilisé pour ajouter du code JS personnalisé à exécuter à la fois sur le portail utilisateur ou lors de l'injection du petit bouton YunoHost ("overlay").
+
+Vous pouvez également ajouter vos propres images et ressources qui peuvent ensuite être utilisées par les fichiers CSS et JS.
+
+### Exemple : personnaliser le logo
+
+Vous pouvez créer votre propre thème simplement pour changer le "branding" du portail utilisateur Yunohost et remplacer le logo YunoHost par votre propre logo !
+
+Pour ce faire, téléversez votre logo dans `/usr/share/ssowat/portal/assets/themes/votre_theme/`, et ajoutez les règles CSS suivantes : 
+
+```css
+/* Dans custom_portal.css */
+#ynh-logo {
+  background-image : url("./votre_logo.png");
+}
+
+/* Dans custom_overlay.css */
+#ynh-overlay-switch {
+  background-image : url("./votre_logo.png");
+}
+```