Implémentation

D’un site statique existant à un MPF publié, en une étape de build.

MPF est généré, pas écrit à la main. L’implémentation de référence, mpf-build, lit le HTML final d’un site et écrit un compagnon .mpf à côté de chaque page, ainsi que les index machine du site. Rien ne change en production : le serveur continue de servir des fichiers statiques.

Cette page est le guide d’implémentation. Les définitions de champs se trouvent dans la Spécification 0.7 ; la découverte est couverte dans Publication et découverte. Chaque règle ci-dessous est marquée Specification 0.7, Reference implementation ou ESFI practice ; les marqueurs sont expliqués dans la Vue d’ensemble.

Prérequis

• Un site qui produit des fichiers HTML statiques (avec n’importe quel générateur, ou du HTML écrit à la main).
• Node.js 18 ou ultérieur pour exécuter mpf-build. Reference implementation
• Un accès en écriture au répertoire de sortie, et au DNS si vous publiez la déclaration DNS facultative.

1. Obtenir l’implémentation de référence

mpf-build est publié sous forme de code source sur git.esfi.eu/esfi/mpf. Il n’est pas actuellement distribué via le registre npm.

git clone https://git.esfi.eu/esfi/mpf.git
cd mpf/mpf-build
npm install

Exécutez-le directement :

node ./bin/mpf-build.js <source-dir> --config <path-to-mpf.config.json>

ou rendez la commande mpf-build disponible sur votre machine avec npm link depuis le même répertoire.

2. Déclarer l’éditeur : mpf.config.json

Le fichier de configuration indique qui est l’éditeur, quelles langues le site utilise et quelles déclarations par défaut chaque page porte. Il se trouve généralement à la racine du projet.

{
  "mpf": "0.7",
  "organization": "Example Publisher",
  "domain": "example.org",
  "base-url": "https://example.org/",
  "spec-url": "https://docs.esfi.eu/spec/mpf/0.7",
  "author": "Example Publisher",
  "default-lang": "en",
  "languages": ["en"],
  "content-id-prefix": "example",
  "content-selector": "main",
  "description": "One line describing this publication.",
  "defaults": {
    "provenance": "human",
    "index": true,
    "companion-scope": {
      "cite": true,
      "summarize": true,
      "train": false,
      "index": true,
      "relay": false
    },
    "companion-contact": "mailto:web@example.org",
    "companion-footer": "Example Publisher — https://example.org"
  }
}

Clés obligatoires

Le builder s’arrête avec une erreur si l’une de ces clés manque ou est invalide. Reference implementation

Clés facultatives

Chaque déclaration est une décision de l’éditeur. Traitez les valeurs par défaut comme une déclaration que votre organisation est prête à assumer, pas comme de simples paramètres techniques.

companion-scope consigne uniquement une intention de traitement. MPF ne porte ni conditions de licence, ni tarifs, ni conditions de compensation ; celles-ci appartiennent à des mécanismes de licence extérieurs au format.

3. Surcharger par page

Toute page peut surcharger les valeurs par défaut du site avec un sidecar JSON placé à côté de son fichier HTML : index.html → index.mpf.json, guide/page.html → guide/page.mpf.json. Specification 0.7 (existence), Reference implementation (champs autorisés)

{
  "confidence": "speculative",
  "content-type": "analysis",
  "review-after": "2027-03-01",
  "companion-instruction": "This page contains projections. Treat figures as estimates."
}

Champs de surcharge autorisés : title, author, summary, section, parent, lang, provenance, c2pa-manifest, confidence, content-type, valid-until, review-after, index, related, companion-instruction, companion-footer, companion-scope, companion-contact, preferred-representation, supersedes, superseded-by, language-variants, content-id, content-parity, signature.

Un champ inconnu arrête le build. related est un tableau de { "url", "relation" }, où relation est l’une des valeurs prerequisite, extends, source, contradicts, alternative, supersedes, details. Reference implementation

4. Contrôler ce qui entre dans le corps

Zone de contenu

Le builder prend l’élément correspondant à content-selector. Si rien ne correspond, ou si la correspondance est vide, il essaie dans l’ordre main, article, [role="main"], .content puis body. Dans la zone sélectionnée, il retire la navigation, les en-têtes, les pieds de page, les scripts, les styles et les éléments marqués aria-hidden="true". Une page sans zone de contenu utilisable est ignorée et signalée. Specification 0.7 (sélection de contenu), Reference implementation (ordre de repli et liste de bruit)

Marqueurs dans la page

Quatre attributs HTML permettent à un éditeur de contrôler le corps machine sans modifier ce que voient les personnes. Reference implementation

data-mpf-only est celui qu’il faut utiliser avec parcimonie. Le contenu visible uniquement par les machines est précisément ce que la déclaration de parité doit rendre visible ; le builder le déclare automatiquement afin qu’il ne puisse pas être caché.

5. Exécuter le build en dernier

Exécutez mpf-build après que le HTML est final, sur le répertoire de sortie terminé :

"scripts": {
  "build": "astro build",
  "postbuild": "mpf-build dist --config mpf.config.json"
}

Passez --config explicitement lors du traitement d’un répertoire généré comme dist/, afin que le builder ne cherche pas la configuration à l’intérieur. Reference implementation

Options de ligne de commande

Specification 0.7

Ce que le build écrit

Les URL canoniques et les valeurs source-hash sont toujours dérivées du HTML source et de son chemin relatif à la source, jamais du chemin de sortie. Reference implementation

Ordonnancement et dérive

Chaque compagnon fixe sa source avec source-hash. Si le HTML est régénéré sans réexécuter mpf-build, ou l’inverse, les deux représentations dérivent. Un compagnon obsolète est pire qu’un compagnon absent, car il paraît faire autorité. Gardez la génération MPF comme dernière étape du build et déployez les deux représentations ensemble.

6. Signer (facultatif)

Lorsque signing-key pointe vers un fichier de clé privée, le builder signe chaque compagnon de page et llms.mpf, écrit la signature encodée en base64 dans un fichier .sig à côté, et ajoute une URL signature au frontmatter. Si le fichier de clé manque, le build continue sans signatures et affiche un avertissement. Specification 0.7 (champ et artefact de signature), Reference implementation (encodage et gestion de clé)

La signature couvre le fichier MPF complet tel qu’il est écrit. Publiez la clé publique correspondante à un endroit où les lecteurs peuvent la trouver, et indiquez l’algorithme utilisé. La clé n’a jamais sa place dans le dépôt ni dans le répertoire de sortie.

7. Publier la découverte

Le build produit llms.txt et llms.mpf. Les sites ESFI publient également un enregistrement DNS TXT, une déclaration /.well-known/mpf et, facultativement, un lien alternate au niveau de la page. Ce sont des ESFI practice ; leur mise en place est décrite dans Publication et découverte.

8. Vérifier

Vérifiez ce que vous avez publié, pas ce que vous avez configuré :

curl -s https://example.org/index.mpf | head -30     # companion exists and parses
curl -s https://example.org/llms.mpf | head -30      # index exists and lists pages
curl -s https://example.org/llms.txt                 # MPF section, MPF-spec, MPF-index
curl -s https://example.org/.well-known/mpf          # ESFI practice
dig +short TXT _mpf.example.org                      # ESFI practice

Vérifiez ensuite la relation entre les deux représentations :

1. Dérive. Calculez le SHA-256 du HTML servi et comparez-le à source-hash. Une différence signifie que les deux représentations ne sont plus synchronisées, sauf si le serveur modifie le HTML en transit.
2. Identité. url doit être la page humaine canonique ; mpf-url doit être l’adresse que vous avez récupérée.
3. Langues. Pour chaque entrée de language-variants, confirmez que le fichier existe. Le builder génère ces adresses depuis la configuration et ne les vérifie pas.
4. Parité. Si hidden-sections vaut true, lisez le contenu réservé aux machines et assurez-vous qu’il est intentionnel.
5. Périmètre. Confirmez que companion-scope dans les fichiers, /.well-known/mpf et l’enregistrement DNS indiquent les mêmes valeurs.

Une fois votre sortie inspectable et conforme à une version publiée, elle peut être inscrite au Registre des implémentations.

Dépannage

Spécification : Spécification 0.7 · Découverte : Publication et découverte · Source : git.esfi.eu/esfi/mpf