HtmGem/index.gmi

# HtmGem, voir Gemini à travers HTTP

Ceci est la page d’installation et de présentation d’**HtmGem**.
=> tests/tutogemtext.gmi Cliquez ici pour voir le tutoriel pour écrire des pages Gemini.

HtmGem permet d’héberger des pages Gemini et de les publier sur le web. À l’ouverture d’une page ***.gmi**, il la traduit en HTML. Cette présente page est affichée de cette façon. Gemini utilise son propre protocole, format, clients et serveurs ; HtmGem permet d’en utiliser le format (Gemtext) via le web.

```
Gemini est un nouveau protocole internet qui :
* est plus lourd que gopher,
* est plus léger que le web,
* n’en remplacera aucun,
* vise le rapport puissance sur poids maximum,
* prend la vie privée très sérieusement.
```
=> https://gemini.circumlunar.space/

=> https://framagit.org/Sbgodin/htmgem Code source de HtmGem
=> https://gmi.sbgodin.fr/htmgem Page principale de HtmGem via le web
=> gemini://gmi.sbgodin.fr/htmgem Page principale de HtmGem via Gemini

———————————————————— ————————————————————

# Installation

Pour faire fonctionner HtmGem — après avoir copié les fichiers — il ne reste qu’à ajouter une règle de ré-écriture d’URL (//URL Rewriting//). Si vous pouvez lire ce texte en ayant demandé //htmgem.php// avec le navigateur, il ne reste que cette dernière étape à franchir 😄

### Nginx
```
# Ce texte doit être placé dans la configuration du serveur.
index index.php index.gmi index.html
rewrite ^(.+\.gmi)$ htmgem/?url=$1;
```

### Apache
```
# Ce texte peut se placer à la racine du site dans un fichier ".htaccess".
DirectoryIndex index.php index.gmi index.html
RewriteEngine on
RewriteRule ^(.+\.gmi)$ htmgem/?url=$1
```

Par la suite,
* Quand un fichier se terminant par **.gmi** sera demandé, HtmGem le traduira à la volée en HTML.
* Quand seul le répertoire sera demandé (http:/​/site.tld/path) le fichier //index.gmi// sera automatiquement choisi.

Le paramétrage d’Apache et de Nginx est similaire. Par la suite, la syntaxe Nginx sera utilisée.

## Tester HtmGem

Il est supposé que HtmGem est installé à la racine du site dans un répertoire //HtmGem//. Sinon, il faudra simplement adapter les liens.

🢂 Appeler cette présente page directement, en cliquant ci-après. Elle devrait être formatée exactement comme actuellement :
=> index.gmi

🢂 Enfin, pour vérifier que le fichier //index.gmi// est automatiquement appelé quand le fichier **.gmi** n’est pas indiqué :
=> /htmgem Lien vers la racine du site

L’installation est terminée 🥳 La suite du texte donne des informations complémentaires, et n’est pas nécessaire dans l’immédiat. Les fichiers **.gmi** que vous créerez seront disponibles dès maintenant.
=> tests/tutogemtext.gmi Inspirez-vous du tutoriel

———————————————————— ————————————————————

# Configuration avancée

Par défaut, le style est incorporé dans chaque page récupérée par le navigateur web. Le même style est utilisé pour toutes les pages, //htmgem/css/htmgem.css//, sauf lorsqu’un fichier ayant le même nom que la page mais avec l’extension **.css** existe dans le même répertoire. Dans ce cas, il est utilisé.

Lorsque l’option css est activé dans la configuration (voir //rewrite// plus haut) d’autres comportements sont possibles :
* &style=**htmgem** : Utilise le style par défaut, mais en tant que fichier externe.
* &style=**none** : La page HTML est envoyée sans style.
* &style=**<autre nom>** : Le fichier htmgem/css/<autre nom>.css est utilisé en tant que style externe.
* &style=**/<path>** : Le fichier indiqué (chemin absolu) est utilisé en tant que style externe.
* &style=**source** : Le code source de la page est envoyée au navigateur, voir ci-après…
* &style=**pre** : Le code source de la page est envoyée au navigateur encadré par des //<pre>//, voir ci-après…

## Réécriture d’URL pour préciser le style à utiliser

Modifier la configuration du serveur web fonctionne mais est assez lourd. On peut tester un style en particulier de la façon suivante :
> https://site.tld/htmgem/index.php?url=/url/page.gmi&style=<…>

Il est aussi possible de faire une réécriture d’URL qui intègre le style :
> rewrite ^(.+\.gmi)$ /htmgem/?url=$1;
> rewrite ^(.+\.gmi)\|([\w_]+)$ /htmgem/?url=$1&style=$2;

Par exemple, lorsque ce sera activé :
=> index.gmi|source Produit le code source, pas bien lisible à l’écran. À utiliser avec //wget//.
=> index.gmi|pre Produit le code source de façon lisble à l’écran en utilisant la balise **<pre>**.

=> index.gmi Ouvre la page avec le style par défaut, avec le style importé dans l’en-tête.

### Avec les styles déjà fournis

=> index.gmi|htmgem Ouvre la page avec le style par défaut (//htmgem.css//), mais le style est importé dans l’en-tête.
=> index.gmi|none Ouvre la page courante avec le style //none//. Aucune CSS utilisée.

=> index.gmi|terminal Style //terminal//
=> index.gmi|black_wide Style //black wide//
=> index.gmi|simple Style //simple//

## Désactiver (ou non) la décoration du texte

La décoration du texte, qui interprête la mise en forme **gras** par exemple, ne fait pas partie de la définition de GemText.
> &textDecoration=0

———————————————————— ————————————————————

# Quand tout marche…

Parmi les fichiers et répertoires distribués, seuls sont utiles :
* **htmgem/index.php** : Il se charge de traduire le gemtext en HTML
* **htmgem/css/htmgem.css** : S’il manque, l’affichage sera dépourvu de style — littéralement.
Les autres peuvent être supprimés (y compris ce présent fichier) bien qu’ils ne présentent aucun danger. Ils restent nécessaires au développement du projet et sont disponibles sur le site de HtmGem. Les autres fichiers du répertoire //css// peuvent servir comme styles alternatifs.