Markdown est un format de texte brut largement pris en charge, qui se lit facilement dans n’importe quel éditeur de texte et s’affiche de façon cohérente d’un outil à l’autre. Wikilayer enregistre le corps de chaque nœud en Markdown, l’analyse avec goldmark + GFM et ajoute quelques extensions propres au projet pour les liens croisés et les encadrés intégrés.
CommonMark et GFM
Tout CommonMark plus GitHub-Flavored Markdown, à une exception près : une ligne de titre dans un corps est refusée, car un titre est la place d’un nœud et le moteur de rendu l’écrit à partir du titre du nœud.
Les corps contiennent donc :
- Gras (
**texte**), italique (*texte*), barré (~~texte~~). - Code en ligne (
`texte`) et blocs de code délimités, avec une indication de langage facultative. - Listes à puces (
-,*,+), listes numérotées (1.), listes imbriquées par indentation. - Blocs de citation (
>). - Tableaux (syntaxe GFM à barres verticales).
- Listes de tâches (
- [x],- [ ]). - Filets horizontaux (
---). - Liens (
[texte](url)) et images ().
Extensions Wikilayer
Quelques formes sont réécrites au moment du rendu.
Références courtes
Une référence courte est un lien écrit d’après l’identifiant d’un nœud, que le moteur de rendu réécrit en URL propre au wiki. Elle survit à un changement de titre ou de slug, car l’identifiant ne bouge pas.
Références courtes de page
[texte](page:N) se résout en URL canonique de la page cible : /{owner}/{wiki}/{id}-{slug}, ou /{owner}/{wiki}/{lang}/{id}-{slug} pour une page dans une langue autre que la langue principale. Le slug peut changer lors d’un renommage ; l’identifiant est stable.
Références courtes de bloc
[texte](block:N) se résout en ancre #block-N : sur la page du bloc, c’est un lien interne à la page ; depuis toute autre page, c’est l’URL de la page du bloc suivie de cette ancre.
Encadrés
Des encadrés visuels, écrits comme des blocs de citation > [!KIND] dans la syntaxe d’encadrés de GitHub.
Types d’encadrés
Les encadrés au format GitHub s’affichent sous forme de boîtes stylisées. La première ligne du bloc de citation nomme le type :
> [!NOTE]
> Texte du corps.
Types pris en charge : NOTE, TIP, IMPORTANT, WARNING, CAUTION. Chacun a sa propre couleur et sa propre icône.
Cartes intégrées
Un encadré [!MAP] avec lat, lng sur la ligne suivante intègre un widget de carte interactive. Une troisième ligne, si elle existe, devient la légende.
> [!MAP]
> 44.7866, 20.4489
> Belgrade, le centre-ville.
Images intégrées
Une image est enregistrée sur le serveur et intégrée au moyen de son chemin /s/. Deux outils MCP permettent de l’enregistrer :
upload_imageaccepte une adresse publiquehttpouhttps, ou un fichier joint à la conversation. Le serveur récupère lui-même l’image, ce qui évite de faire passer ses octets par le contexte de l’agent. Cet outil convient à un agent dans une conversation de navigateur, sans accès à un shell.request_uploaddélivre une adresse à usage unique vers laquelle un agent disposant d’un shell envoie un fichier local :curl --data-binary @<file> -H 'Content-Type: <mime>' '<upload_url>'.
Dans les deux cas, l’image est convertie en JPEG, avec un côté le plus long de 1600 px au maximum, et enregistrée dans le wiki. upload_image renvoie son chemin ; avec request_upload, c’est la requête POST qui le renvoie. Le chemin est inséré directement dans le corps, exactement tel qu’il a été renvoyé : .
À côté du texte, avec une légende
Une image seule dans un paragraphe occupe toute la largeur du texte. Si elle a un titre, elle se place à droite du texte, comme une vignette dans une encyclopédie : le titre devient sa légende, le texte s’écoule à sa gauche et un clic ouvre l’image entière.
Le texte alternatif décrit l’image pour les lecteurs qui ne peuvent pas la voir ; la légende indique ce qu’il faut en retenir. Une image haute, ou qui illustre plutôt qu’elle n’explique, se lit mieux à côté du texte. Une capture d’écran ou un diagramme dont les détails comptent conserve la pleine largeur.
Sur un écran de la largeur d’un téléphone, l’image occupe toute la largeur ; les applications mobiles affichent toutes les images en pleine largeur.
Aucun hébergeur externe
Une image ne s’intègre que depuis le stockage propre au wiki, par son chemin /s/. Une écriture qui désigne une image sur GitHub, Imgur ou un autre hébergeur, une URI data: ou une URL complète est refusée, et une image venue d’ailleurs déjà présente dans un corps s’affiche comme un lien. Les images externes finissent par disparaître, se heurtent à des limites de débit et indiquent à leur hébergeur qui a lu la page.
Sans stockage objet, il n’existe aucun contournement
Si ni upload_image ni request_upload n’apparaissent dans la liste des outils, le stockage objet n’est pas configuré sur cette instance et l’intégration d’images n’est pas disponible ; un hébergeur externe ne la remplace pas.