HtmGem/index.gmi

# HtmGem, voir Gemini via le web

Ceci est la page d’installation et de présentation d’**HtmGem**.
=> 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 un serveur web muni de **Php**. À l’ouverture d’une page ***.gmi**, il la traduit pour le navigateur web. 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/-/archive/master/htmgem-master.zip Téléchargez htmgem-master.zip pour l’installer
=> https://framagit.org/Sbgodin/htmgem Code source, rapports de bug, commentaires…

=> https://gmi.sbgodin.fr/htmgem Page principale de HtmGem via le web
=> gemini://gmi.sbgodin.fr/htmgem Page principale de HtmGem via Gemini

=> CHANGELOG.gmi Journal des modifications (//changelog//)
=> COPYING.gmi GNU Affero General Public License (AGPLv3)

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

# 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 😄

## Prérequis

* Php v7.3 minimum
* Module **Php-mbstring** pour gérer l’unicode
* Un serveur web (Apache et Nginx testés)
* Module **mod-rewrite** pour intercepter les pages Gemini

### 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.

Chargez cette présente page directement, en cliquant ci-après.
=> index.gmi

Enfin, pour vérifier que le fichier //index.gmi// est automatiquement appelé quand le fichier **.gmi** n’est pas indiqué :
=> /htmgem

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.
=> 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%20|%20source Le lien index.gmi | source Produit le code source, pas bien lisible à l’écran. À utiliser avec //wget//.
=> index.gmi%20|%20pre 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.

=> css Sélecteur de style : une page de démo pour essayer chaque style 😎

### Avec les styles déjà fournis

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

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

## Décoration du texte

La décoration du texte, qui interprête le **gras** par exemple, ne fait pas partie de la définition de GemText. La décoration du texte s’applique partout sauf sur les titres et blocs préformatés.

### Désactiver la décoration du texte

On peut :
* commencer la ligne par **^**,
* faire un bloc non décoré avec **^^^**,
* ajouter ce qui suit à la **réécriture** d’URL :
> &textDecoration=0

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

# Quand tout marche…

Parmi les fichiers et répertoires distribués, seuls sont utiles pour le fonctionnement de HtmGem :
* **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.
* **htmgem/css/… : Conservez les styles que vous utilisez.
Les autres peuvent être supprimés (y compris ce présent fichier //index.gmi//) bien qu’ils ne présentent aucun danger.