Nom
docs - le manuel de tilder
Ce manuel décrit tilder 1.4.1 : chaque clé de configuration, chaque clé d'en-tête, chaque construction Markdown, chaque variable de gabarit, chaque classe et chaque option de la ligne de commande de cette version. Il s'adresse à celles et ceux qui s'en servent pour construire un site. Commencez par le guide ; revenez à la référence quand un détail vous manque.
Sections
- Guide : de la première construction au site en ligne, dans l'ordre où les questions se posent.
- Types de contenu : les collections, les articles, les événements, les membres, vos propres types, et l'ordre des pages d'une collection.
- Thèmes : de quoi un thème est fait, ses gabarits, ses variables, ses classes et ses scripts, et comment le vérifier.
- Référence : le dialecte Markdown, chaque clé de la configuration, le miroir en texte, le référencement, les flux et les images, la ligne de commande.
Dans un terminal
Comme tout site construit par tilder, ce manuel a son double en texte, sur 75 colonnes. Un terminal le reçoit à la même adresse :
curl tilder.thosted.fr/fr/docs
curl tilder.thosted.fr/fr/docs/guide/getting-startedPages
Guide
Le parcours de tilder, page après page : l'installer, organiser un projet, écrire des pages, ajouter une langue, puis mettre le site en ligne.
Premiers pas
Installer tilder avec Docker ou Python 3.11, copier le site de départ, le construire, le reconstruire en écrivant, et s'y retrouver dans public/.
Le projet
Les trois dossiers d'un site tilder, content/, theme/ et assets/, les trois couches de sa configuration, et ce qui est servi.
Écrire des pages
D'un fichier Markdown à une page : son adresse, chaque clé de l'en-tête, les sections de page de manuel, les liens entre langues, les images.
Langues
Servir un site en plusieurs langues : les déclarer, traduire la configuration et les pages, et savoir ce que devient une page pas encore traduite.
Déploiement
Mettre un site tilder en ligne avec Docker, compose et Caddy : URL propres, miroir en texte pour curl, hôte en texte brut, en-têtes, autres serveurs.
Types de contenu
Les collections de pages d'un même type : les déclarer, leurs éléments, les marqueurs de liste, leurs flux RSS et iCalendar, et les quatre types fournis.
page
Le type page : tout fichier Markdown hors d'une collection, sans réglage, sans carte ni liste, décrit aux moteurs de recherche comme une WebPage.
post
Le type post : des articles datés, nommés par leur date, listés du plus récent au plus ancien par {posts}, avec un flux RSS et des données BlogPosting.
event
Le type event : des éléments datés avec un lieu, à venir ou passés selon la date de construction, les listes {upcoming}, {past}, {next-event}, les flux.
member
Le type member : une page par personne, une grille qu'on peut filtrer avec {members}, des catégories, les pronoms, les profils publics et members.js.
Vos propres types
Écrire un type de contenu en Python dans theme/types/ : ses attributs, ses fonctions, l'élément, le nœud de carte, les marqueurs, les imports, les erreurs.
Navigation
L'ordre des pages d'une collection, leurs groupes et leurs sections, la barre latérale, les liens vers la page précédente et suivante, leur ligne en texte.
Thèmes
Ce qu'est un thème tilder, comment en utiliser un, et les pages qui décrivent ses fichiers, ses gabarits, ses classes, ses scripts et ses vérifications.
Les fichiers d'un thème
Chaque fichier qu'un thème tilder peut fournir, ce qu'en fait la construction, ce qu'elle sert, et comment assets/ prend le pas sur le thème.
Gabarits et variables
layout.html et layouts/, comment tilder choisit le gabarit d'une page, chaque variable avec sa valeur et son échappement, et ce qu'un gabarit doit garder.
Classes
Chaque classe que tilder écrit dans son HTML, regroupée comme dans son contrat, avec l'élément qui la porte, et l'accessibilité qui revient au thème.
Scripts
Les scripts qu'un thème tilder peut fournir, code.js, members.js et celui d'un type, où la construction charge chacun, et les règles qu'ils suivent.
Vérifier un thème
build.py --check vérifie un thème au regard du tilder qui l'exécute : une règle pour chaque classe écrite, et le contraste des paires de couleurs.
Référence
Chaque détail de tilder, à consulter : le dialecte Markdown, la configuration, le miroir en texte, le SEO, les flux, les images et la ligne de commande.
La référence Markdown
Le dialecte Markdown de tilder sur une page : ses principes, un aide-mémoire de chaque construction, et ce qu'il laisse de côté exprès.
Sections
Les titres ## d'une page : les rangées de manuel qu'ils dessinent, l'identifiant de chacun, et chaque marqueur entre accolades qui change une section.
Blocs
Paragraphes et classes, état vide, listes, tâches, sommaire, filets, encadrés, alertes, blocs de code, tableaux et commentaires, chacun montré rendu.
Entrées
Les titres ### d'une section : un événement, une personne, une carte. Leur ligne meta de dates et d'étiquettes, leur corps en retrait, leurs marqueurs.
Balisage en ligne
Gras, italique, texte barré et souligné, code et liens au fil d'une phrase : les six constructions en ligne, ce qui reste littéral, et le miroir en texte.
Liens et images
Cibles des liens écrites depuis la racine, ancres, liens entre langues, fichiers et autres sites ; images à côté de leur page, texte de remplacement, légendes.
Configuration
Chaque clé du defaults.toml de tilder, table par table : sa valeur par défaut, son rôle, et un exemple de réglage dans site.toml.
Le miroir en texte
Chaque page en texte : 75 colonnes, ramenée à l'ASCII, brute dans txt/ et en couleur dans ansi/, avec le code encadré et l'hôte en texte brut.
SEO
Ce qu'écrit tilder pour les moteurs de recherche et les aperçus de lien : titre, description, canonique, Open Graph, JSON-LD, plans du site, robots.txt.
Flux et images
Les fichiers qu'écrit tilder à côté des pages : flux RSS, iCalendar, icônes et share.png dessinés depuis le SVG à chaque construction, manifeste web.
La ligne de commande
build.py et chacune de ses options, de --root à --check, ce qu'affiche la construction, chaque avertissement et erreur, et ses codes de sortie.