Machine Page Format (MPF) 0.6

Version précédente. MPF 0.6 reste publié afin que les documents qui le déclarent puissent être interprétés selon leur contrat d’origine. La version actuellement implémentée est MPF 0.7.

Statut : spécification implémentée
Version : 0.6
Implémentation de référence : mpf-build

Machine Page Format (MPF) est une représentation compagnon, lisible par machine, générée à partir d’une page web. MPF 0.6 est défini ici par le comportement de l’implémentation actuelle de mpf-build. Ce document décrit ce que cette implémentation produit ; il ne définit pas de comportement futur non implémenté.

1. Forme du fichier

Un document MPF est un texte UTF-8 avec un frontmatter YAML suivi d’un corps Markdown.

---
mpf: '0.6'
title: Example
...
mpf-id: <sha256>
---

# Markdown body

Le frontmatter est sérialisé dans un ordre d’insertion stable. Le corps est tronqué de ses espaces superflus avant sérialisation et le document final se termine par un saut de ligne.

1.1 Identifiant MPF

mpf-id est un condensat SHA-256 du document MPF généré complet avant l’insertion du champ mpf-id lui-même.

La source exacte du condensat est :

---
<serialized YAML without mpf-id>
---

<body>

mpf-id est donc un identifiant de contenu de la représentation MPF générée, et non du HTML source.

1.2 Hash source

source-hash est un condensat SHA-256 du HTML source brut lu par mpf-build.

2. Génération des pages

mpf-build parcourt récursivement le répertoire source, ignore les entrées cachées et node_modules, et traite les fichiers se terminant par .html ou .htm.

Pour chaque page, il :

1. lit le HTML brut et la date de modification du fichier ;
2. charge la configuration du site et tout override de page ;
3. analyse les métadonnées de la page ;
4. extrait le contenu réservé à MPF et applique les transformations HTML MPF de l’implémentation ;
5. sélectionne la zone de contenu configurée ;
6. retire le bruit qui n’appartient pas au contenu ;
7. convertit le HTML sélectionné en Markdown ;
8. ajoute des ancres stables aux titres et construit la table des matières ;
9. ajoute en tête le Markdown réservé à MPF, s’il existe ;
10. résout les métadonnées canonical, MPF, d’identité, de langue et de provenance ;
11. ajoute en tête un bloc d’instruction compagnon lorsqu’il est configuré ;
12. sérialise le document MPF et l’écrit dans l’arborescence de sortie ;
13. écrit une signature à côté du document MPF lorsqu’une signature est configurée.

Le répertoire de sortie est par défaut le répertoire source et peut être remplacé avec --out.

3. Frontmatter

3.1 Champs émis pour une page

Le générateur de page actuel émet les champs suivants :

L’implémentation peut également émettre les champs facultatifs suivants lorsqu’ils se résolvent vers une valeur non vide :

• c2pa-manifest
• section
• parent
• related
• summary
• index
• confidence
• valid-until
• review-after
• content-type
• companion-instruction
• companion-contact
• preferred-representation
• companion-scope
• supersedes
• superseded-by
• language-variants
• signature

Le générateur s’arrête avec une erreur si la page n’a pas de titre, d’URL canonique, de provenance ou de content ID.

3.2 Résumé

summary est résolu dans cet ordre :

1. summary de l’override de page ;
2. description des métadonnées HTML ;
3. omission du champ.

3.3 Parité du contenu

Si le HTML contient du contenu réservé à MPF détecté par l’implémentation, le frontmatter de page est forcé à :

content-parity:
  html: false
  human-visible-source: false
  hidden-sections: true

Sinon, content-parity utilise la valeur par défaut configurée. Si aucune valeur par défaut n’est configurée, l’implémentation utilise :

content-parity:
  html: true
  human-visible-source: true
  hidden-sections: false

4. URL et identité

4.1 URL canonique

Si les métadonnées de la page fournissent une URL canonique, celle-ci est résolue par rapport à l’URL de base configurée et utilisée. Pour une page index.html, le chemin canonique est normalisé pour se terminer par /.

Sans métadonnée canonique de page :

• le index.html racine se résout vers l’URL de base normalisée suivie de / ;
• les autres chemins HTML se résolvent sous l’URL de base configurée après suppression d’un index.html terminal.

4.2 Content ID

L’identité de page générée a cette forme :

<content-id-prefix>:page:<slug>

Le préfixe de locale configuré est supprimé avant la génération du slug, de sorte que les traductions de la même route reçoivent le même content ID généré.

Le slug de la page racine est home.

Pour les pages non racine, la route est convertie en minuscules, les segments du chemin sont joints par des tirets et les caractères non pris en charge sont normalisés en tirets.

Exemple de l’implémentation ESFI :

esfi:page:home

4.3 Détection de langue

Les langues configurées proviennent de config.languages. Si cette liste est vide ou absente, seule la langue par défaut configurée est utilisée.

Le générateur examine le premier segment du chemin. S’il s’agit d’un code de langue configuré, cette langue est attribuée ; sinon la langue par défaut est attribuée.

4.4 Variantes linguistiques

Pour chaque langue configurée, le générateur produit une entrée language-variants pointant vers l’URL MPF attendue pour le même chemin de contenu indépendant de la locale.

Pour la langue par défaut, aucun préfixe de locale n’est inséré. Les variantes non par défaut reçoivent /<lang>/.

L’implémentation génère ces URL à partir de la configuration et de l’identité du chemin ; elle ne vérifie pas à cette étape que chaque fichier traduit existe.

Exemple :

language-variants:
  en: https://esfi.eu/index.mpf
  fr: https://esfi.eu/fr/index.mpf
  nl: https://esfi.eu/nl/index.mpf
  de: https://esfi.eu/de/index.mpf

5. Corps Markdown et table des matières

Le contenu HTML sélectionné est converti en Markdown avant la sérialisation MPF.

Les titres H1 à H4 sont inclus dans toc et reçoivent des ancres Markdown explicites :

## Example heading {#example-heading}

Chaque entrée de la table des matières a la forme :

- level: 2
  text: Example heading
  id: example-heading

La génération des ancres :

• convertit le titre en minuscules ;
• conserve les lettres et chiffres Unicode ;
• remplace les autres séquences par - ;
• fusionne les tirets répétés ;
• retire les tirets en début et en fin ;
• utilise section si aucun slug ne reste ;
• résout les doublons en ajoutant -2, -3, etc.

Les titres à l’intérieur de blocs de code fenced sont ignorés.

La mise en forme Markdown en ligne et les liens existants sont retirés du texte du titre utilisé pour l’identité dans la table des matières.

6. Instruction compagnon

Si companion-instruction est présent, le générateur le place au début du corps Markdown sous forme de blockquote.

Forme sur une ligne :

> Companion instruction: <instruction>

Forme multiligne :

> Companion instruction:
> <line 1>
> <line 2>

7. Index du site

Un build produit également trois sorties de découverte au niveau du site :

• llms.mpf
• llms.txt
• llms-full.txt

7.1 Pages indexées

Une page n’est incluse dans les index générés que si son frontmatter résolu contient :

index: true

Les entrées indexées sont triées lexicalement par URL MPF.

7.2 llms.mpf

llms.mpf est lui-même un document MPF 0.6. Son frontmatter généré utilise :

• le titre Site Index — <organization> ;
• la langue = langue par défaut configurée ;
• la provenance = human ;
• le type de contenu = reference ;
• index: true ;
• content-id: <content-id-prefix>:page:llms ;
• une parité de contenu cachée/non HTML.

Son corps contient le titre de l’organisation, la description configurée facultative et une liste Markdown de toutes les pages MPF indexées. Chaque élément inclut le résumé de la page lorsqu’il existe.

L’implémentation actuelle inclut dans llms.mpf les pages indexées de toutes les langues configurées.

7.3 llms.txt

Le générateur maintient une section de découverte MPF dans llms.txt :

MPF: <version>
MPF-index: /llms.mpf

## Pages
...

Si aucun llms.txt n’existe, le générateur en crée un avec un titre d’organisation. Si une section MPF précédente existe, il remplace cette section tout en préservant le contenu avant et après.

7.4 llms-full.txt

llms-full.txt concatène uniquement les corps des pages indexées dans la langue par défaut configurée.

Pour chaque page, il écrit le titre, l’URL canonique et le corps MPF généré.

8. Signature

Le générateur charge une clé de signature depuis le paramètre de clé de signature configuré.

Lorsqu’une clé de signature est disponible :

• le frontmatter de page reçoit une URL signature ;
• llms.mpf reçoit également une URL signature ;
• l’implémentation écrit un artefact de signature à côté du contenu MPF généré.

Lorsqu’aucune clé de signature n’est configurée, le champ signature est omis.

9. Interface en ligne de commande

La CLI implémentée est :

mpf-build <source-dir> [options]

Options :

En mode watch, les demandes de reconstruction sont sérialisées : si un changement se produit pendant un build en cours, un seul build supplémentaire est mis en file et exécuté ensuite.

10. Configuration de référence ESFI 0.6

Le déploiement ESFI 0.6 utilisait :

{
  "mpf": "0.6",
  "organization": "European Strategy & Future Infrastructure",
  "domain": "esfi.eu",
  "base-url": "https://esfi.eu/",
  "author": "ESFI",
  "default-lang": "en",
  "languages": ["en", "fr", "nl", "de"],
  "content-id-prefix": "esfi"
}

Ce déploiement définissait également des valeurs par défaut pour la provenance, la confidence, le type de contenu, l’indexation, le companion scope, le companion contact, la représentation préférée et la parité du contenu.

11. Non-revendications

MPF 0.6 n’acquiert pas une capacité simplement parce qu’un nom de champ pourrait la décrire. Cette spécification ne revendique que le comportement présent dans l’implémentation de référence.

En particulier, les métadonnées générées telles que language-variants, confidence, companion-scope, valid-until ou review-after sont des métadonnées descriptives. Le générateur les émet ou les dérive comme décrit ci-dessus ; aucune politique supplémentaire, validation réseau, vérification de traduction, application d’expiration ou calcul de confiance n’est impliqué par l’implémentation 0.6.