~/tilder/, fr/, Documentation/, Types de contenu

content types - les collections, et les types qui leur donnent forme

Une collection est un dossier de content/ dont les fichiers sont les éléments d'un même type : les articles d'un blog, les événements d'un agenda, les membres d'un groupe. Le type dit ce qu'est un élément : les clés d'en-tête qu'il lit, sa carte dans une liste, ses données structurées, son flux. tilder fournit quatre types, et un thème ajoute les siens en Python. Cette page déclare les collections et les liste ; les pages suivantes décrivent chaque type.

Un thème ajoute des types dans theme/types/, écrits exactement comme ceux de tilder (vos propres types). Ce manuel est lui-même une collection du type doc du thème, et sa vitrine une collection d'un type showcase.

Une collection est une table de site.toml, [collections.<name>]. Son nom est celui par lequel les marqueurs et la clé d'en-tête feed: la désignent.

[collections.talks]         # {upcoming:talks}, {past:talks}
type = "event"
dir = "talks"               # content/talks/, served at /talks/...
feed = "talks.xml"
calendar = "talks.ics"
upcoming_tag = "soon"

Les réglages de chaque type sont listés sur sa page. Un site.fr.toml peut reprendre [collections.<name>] avec les seuls mots qui changent : les tables sont fusionnées clé par clé, si bien que le flux français reçoit un titre en français tandis que type et dir restent tels que site.toml les fixe (langues).

Un type qu'aucun module ne définit arrête la construction, qui nomme les types chargés :

error: content/site.toml: collection "talks" has type "tlak", which no type defines. Types loaded: event, member, page, post (types/)

Le defaults.toml de tilder déclare les trois collections que la plupart des sites ont :

[collections.blog]
type = "post"
dir = "blog"
feed = "blog/feed.xml"

[collections.events]
type = "event"
dir = "events"
nav = "events"
feed = "events.xml"
calendar = "calendar.ics"

[collections.members]
type = "member"
dir = "members"

Une collection dont le dossier n'existe pas est inactive : pas d'élément, pas de flux, pas de calendrier, et un marqueur qui la nomme affiche son texte de liste vide. Un site commence donc un blog en créant content/blog/, sans rien configurer. Un [collections.blog] dans site.toml est fusionné avec celui par défaut : ce site y règle son nom de page de manuel et les mots de son flux. Le résumé de la construction dit quelles collections sont actives :

collections: blog (post, 3 items), events (event, no folder), members (member, no folder)

Un élément est un fichier du dossier de la collection, ou un dossier à lui seul :

• Un type daté, post ou event, lit sa date dans le nom du fichier, YYYY-MM-DD-slug.md (post).
• La page de la collection est <dir>/index.md, ou une page nommée comme le dossier, à côté de lui (talks.md pour talks/). C'est une page ordinaire : elle fixe elle-même son man, son tagline et son nav, et porte la liste.
• Avec les types fournis, l'en-tête d'un élément peut omettre man, nav et, pour les types datés, tagline : le type les remplit à partir des réglages de la collection.

Avec recursive = true (tilder 1.2), une collection lit aussi ses sous-dossiers, à toute profondeur. content/docs/guide/writing.md est l'élément guide/writing, servi à /docs/guide/writing, dans la section guide. Le index.md d'un sous-dossier est l'élément nommé comme le dossier, servi à côté de lui : content/docs/guide/index.md est /docs/guide, la page de la section. Un guide.md à côté du dossier peut tenir ce rôle à sa place ; une section qui n'a ni l'un ni l'autre n'a pas de page, et le nom de son dossier la représente. La documentation que vous lisez est une telle collection.

recursive vaut false sauf si la collection ou les réglages de son type le fixent, et ne prend que true ou false. Un type daté ne peut pas être récursif, et deux fichiers pour un même élément (guide.md et guide/index.md) arrêtent la construction. L'ordre des pages, en profondeur d'abord, est décrit sur la page navigation.

Un titre de section qui se termine par le marqueur d'un type est rempli des cartes de la collection, une par élément ; la carte d'un article ou d'un événement est cliquable en entier :

## Posts {posts}

## Coming up {upcoming:talks}

• {marker:name} nomme la collection à lister : {posts:news}, {upcoming:talks}. Un nom qui n'est pas une collection du type du marqueur arrête la construction.
• Un {marker} seul liste la collection de ce type propre à la page : celle dont le dossier contient la page, ou dont la page porte le nom ; à défaut, la première collection de ce type.
• Une liste vide affiche le texte prévu par la collection : empty pour les articles et les membres, none_upcoming et none_past pour les événements.
• Les blocs écrits sous le titre restent, après les cartes.
• Le mot du marqueur devient aussi une classe du corps de la section (.posts, .upcoming), et une grille de membres ajoute .grid (classes).

Le type d'un thème apporte ses propres marqueurs, comme les {docs} et {showcase} de ce site.

Chaque collection peut écrire deux fichiers, chacun désigné dans ses réglages par un chemin depuis la racine du site ; un chemin vide n'écrit rien.

• feed : un flux RSS de tous les éléments, dans l'ordre inverse de la collection (du plus récent au plus ancien pour les articles et les événements), pour les types qui fournissent des entrées de flux (post et event, pas member). Le flux est écrit dans chaque langue, sous son préfixe : blog/feed.xml et fr/blog/feed.xml, avec les mots de feed_title et feed_description dans cette langue. La clé d'en-tête feed: d'une page, un nom de collection ou all, annonce le flux dans son <head> (écrire des pages).
• calendar : un fichier iCalendar de tous les événements, pour le type event. Il est écrit une seule fois, dans la langue par défaut : un calendrier n'a pas de langue d'interface (event).

Tous les calendriers du site partagent la table [calendar] :

[calendar]
name = "talks"
description = "Talks of the group."
prodid = "-//example.org//talks//EN"
uid_domain = "example.org"

Comme le calendrier est écrit dans la langue par défaut, il prend ces valeurs dans site.toml ; un [calendar] dans site.fr.toml n'est pas utilisé.

• page, post, event, member
• vos propres types
• navigation
• flux et images