# Gemtext

## Ce que c'est

Gemtext est le format documentaire du protocole Gemini : du texte brut encodé en UTF-8 où les premiers caractères de chaque ligne en déterminent le type. Un client peut ainsi afficher toute une page en un passage de haut en bas. La spécification le nomme format hypertexte Gemini, les serveurs l'étiquettent `text/gemini` et les fichiers se terminent habituellement par `.gmi`.

Il existe six types de ligne. Une ligne commençant par `=>` est un lien : une adresse absolue ou relative, suivie d'un libellé facultatif. Une ligne de trois accents graves active ou désactive le mode préformaté ; tout ce qui figure entre deux de ces lignes s'affiche tel quel en police à chasse fixe. Un, deux ou trois croisillons forment un titre ; un astérisque suivi d'une espace, un élément de liste ; un signe supérieur, une citation. Toute autre ligne est du texte ordinaire, que le client renvoie à la ligne selon la largeur de l'écran.

```text
# Notes de terrain

Toute ligne de texte est un paragraphe. Le client gère le retour à la ligne.

=> /archive/ Notes plus anciennes
=> gemini://example.org/ Une capsule ailleurs

* Un élément de liste
> Une ligne citée
```

La spécification répartit ces six types entre trois types essentiels que tout client doit gérer, texte, liens et bascule du préformatage, et trois qu'un client minimal peut afficher en texte simple. C'est tout le format. Il n'a ni gras, ni italique, ni tableaux, ni images dans le texte, ni imbrication, ni moyen de rendre cliquable un mot au milieu d'une phrase. L'analyseur garde un seul bit d'état : s'il se trouve dans un bloc préformaté.

On compare surtout gemtext à Markdown, auquel il ressemble à première vue. La différence tient à leur rôle. Un fichier Markdown est une source destinée à être convertie ; un fichier gemtext est déjà le document fini et le client du lecteur est son seul moteur de rendu. Il emprunte aux anciens menus Gopher son habitude structurelle : le lien sur sa propre ligne.

## Pourquoi c'est important

Choisir gemtext, c'est choisir qui contrôle la page. L'auteur décide de la structure : quelles lignes sont des titres ou des liens, où se trouve le code. Le client du lecteur décide de tout le reste : police, longueur de ligne, couleur, espacement, table des matières éventuelle à partir des titres. La spécification précise que le format ne vise pas à donner un contrôle fin de la présentation aux auteurs. Pour certains éditeurs, c'est un soulagement ; pour d'autres, cela suffit à écarter l'option. Mieux vaut le savoir avant de convertir la moindre page.

Le soulagement vient de ce qui disparaît. Une page gemtext ne contient ni feuille de style, ni script, ni police web, ni avis sur les cookies, ni pixel de suivi. Seuls les mots demandent une actualisation. Les pages sont petites et rapides à écrire à la main. Les liens ne récupèrent rien d'eux-mêmes : la spécification interdit au client d'ouvrir une connexion réseau simplement pour afficher un lien. Une page ne peut donc charger une image ou une police tierce à l'insu du lecteur.

Le coût est tout aussi concret. Gemtext ne touche que les personnes utilisant un client Gemini, public restreint face au Web. Il n'a pas de formulaires : une capsule ne demande une saisie que par un code d'état du protocole, rien dans le document. La prose doit se passer de liens dans les phrases. Une phrase HTML comme « consultez la page des tarifs pour en savoir plus » garde ses mots, mais n'offre plus de lien à suivre dans la phrase. Bien écrire gemtext, c'est écrire des phrases qui restent compréhensibles avec le lien sur la ligne suivante.

Pour la plupart des organisations, la question réaliste est donc d'ajouter gemtext au site web plutôt que de le remplacer, depuis la même source et avec la même compilation. Cela coûte peu et teste aussi l'écriture. Si une page reste claire dans une colonne de lignes de texte et de liens, sa structure était déjà dans les mots.

## À quoi cela ressemble en pratique

Ce site est publié en gemtext à côté du HTML. La page [Engineer dans un terminal](/fr/cli/) donne l'adresse `gemini://engineer.company/`, précise que toutes les pages existent aussi dans ce format et nomme des clients : Amfora, Lagrange et Bombadillo dans un terminal ; Castor et Kristall dans une fenêtre. Elle en explique la raison. Un déploiement écrit un dossier que lisent toutes les portes d'entrée : la copie gemtext ne peut diverger du HTML. Une page qui se lit bien en gemtext a une structure réelle, pas seulement dessinée.

Le [récit de la réplication du site vers Gemini et Gopher](/fr/portfolio/mirrored-the-site-to-gemini-and-gopher/) explique sa construction. Gemtext est une sortie de la même compilation, pas une chaîne d'outils séparée. Le générateur a reçu des types de médias et formats de sortie spécifiques ; chaque page, section et terme de taxonomie a gagné un document Gemini à côté de son HTML et de son jumeau Markdown. Il y en avait 777 à l'étape d'implémentation documentée, servis par un petit démon sur le même hôte. Ces nouveaux formats sont marqués comme représentations non alternatives. Une comparaison de compilations distincte a mesuré zéro octet HTML modifié par leur ajout ; elle n'a pas mesuré les changements éditoriaux ou visuels ultérieurs.

Les modèles montrent le travail de conversion. Chaque lien est extrait de sa phrase : les mots restent où elle en a besoin et l'adresse descend sur sa propre ligne `=>`. Les marques de gras disparaissent, les puces en traits d'union deviennent des astérisques et les blocs de code délimités restent intacts : la délimitation Markdown et la bascule de préformatage gemtext emploient les mêmes trois accents graves.

## Où les problèmes surviennent

### Des demi-lignes qui ne se rejoignent jamais

La prose arrive sous forme de colonne irrégulière de lignes courtes, coupées au milieu d'une proposition. La source était coupée à 80 colonnes, comme souvent en Markdown, et la spécification interdit au client d'assembler les lignes de texte courtes consécutives en lignes plus longues. Écrivez chaque paragraphe sur une seule longue ligne ou faites réunir les lignes d'un même paragraphe par le convertisseur avant d'écrire le fichier.

### Des liens qui quittent la capsule

Le premier lien suivi ouvre un navigateur web. Le convertisseur a écrit tous les liens comme adresses `https://` absolues, que le client Gemini transmet à un autre programme. Écrivez la navigation avec des chemins relatifs à la racine comme `/about/`, résolus dans la capsule, et gardez un lien délibéré par page vers sa version web.

### Du code réduit à une seule ligne

Un exemple de code s'affiche en une longue ligne collée à sa délimitation d'ouverture. Le convertisseur a traité le bloc comme de la prose et joint ses lignes au reste. Découpez le document sur ses délimitations avant toute autre étape, conservez chaque bloc préformaté tel quel et limitez le texte alternatif de la ligne de bascule à une indication courte, comme le nom du langage.

### Du Markdown affiché en caractères littéraux

Puces en traits d'union, doubles astérisques, titres soulignés, listes imbriquées et liens entre crochets s'affichent tels qu'ils sont écrits. Gemtext ne reconnaît qu'un astérisque suivi d'une espace pour une puce, et des croisillons pour un titre ; il n'a aucun balisage dans les phrases. Convertissez ces constructions en sortie ou écrivez directement en gemtext.

### Des phrases qui ne pointent nulle part

Un paragraphe dit « cliquez ici » ou « comme indiqué dans le lien ci-dessus » sans que le lecteur sache où aller. Le lien a quitté la phrase et les mots restants ne nommaient pas sa destination. Écrivez des libellés qui la nomment, afin que la phrase et la ligne `=>` se comprennent séparément.

## Pour aller plus loin

- [Brève introduction au balisage gemtext](https://geminiprotocol.net/docs/gemtext.gmi)
  — Le tour des types de ligne par le projet, avec des notes pour les habitués de Markdown.
- [Spécification du format hypertexte Gemini](https://geminiprotocol.net/docs/gemtext-specification.gmi)
  — Le texte normatif : types de ligne, état de l'analyseur, règles de retour à la ligne, paramètre `lang` et grammaire formelle.
- [Spécification du protocole réseau Gemini](https://geminiprotocol.net/docs/protocol-specification.gmi)
  — Comment une capsule sert gemtext : requêtes, codes d'état et règles TLS du client.
- [FAQ du projet Gemini](https://geminiprotocol.net/docs/faq.gmi)
  — Les raisons du choix de format, dont les liens sur leurs propres lignes.

<https://engineer.company/fr/glossary/gemtext/>
