Machine Page Format (MPF) 0.6

Vorherige Version. MPF 0.6 bleibt veröffentlicht, damit Dokumente, die diese Version deklarieren, anhand ihres ursprünglichen Vertrags interpretiert werden können. Die aktuell implementierte Version ist MPF 0.7.

Status: implementierte Spezifikation
Version: 0.6
Referenzimplementierung: mpf-build

Machine Page Format (MPF) ist eine generierte, maschinenlesbare Companion-Repräsentation einer Webseite. MPF 0.6 wird hier durch das Verhalten der mpf-build-Implementierung dieser Version definiert. Dieses Dokument beschreibt, was diese Implementierung erzeugt; es definiert kein noch nicht implementiertes zukünftiges Verhalten.

1. Dateiform

Ein MPF-Dokument ist UTF-8-Text mit YAML-Frontmatter, gefolgt von einem Markdown-Body.

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

# Markdown body

Das Frontmatter wird in stabiler Einfügereihenfolge serialisiert. Der Body wird vor der Serialisierung getrimmt, und das endgültige Dokument endet mit einem Zeilenumbruch.

1.1 MPF-Identifikator

mpf-id ist ein SHA-256-Digest des vollständigen erzeugten MPF-Dokuments bevor das Feld mpf-id selbst eingefügt wird.

Die Digest-Quelle ist exakt:

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

<body>

Damit ist mpf-id ein Content-Identifikator für die erzeugte MPF-Repräsentation, nicht für das Quell-HTML.

1.2 Source Hash

source-hash ist ein SHA-256-Digest des rohen Quell-HTML, das mpf-build liest.

2. Seitengenerierung

mpf-build durchläuft das Quellverzeichnis rekursiv, ignoriert versteckte Einträge und node_modules und verarbeitet Dateien mit der Endung .html oder .htm.

Für jede Seite:

liest es das rohe HTML und den Änderungszeitpunkt der Datei;
lädt es die Site-Konfiguration und ein etwaiges Seiten-Override;
parst es die Seitenmetadaten;
extrahiert es MPF-only Material und wendet die von der Implementierung verwendeten MPF-HTML-Transformationen an;
wählt es den konfigurierten Inhaltsbereich;
entfernt es Nicht-Inhaltsrauschen;
konvertiert es das ausgewählte HTML in Markdown;
ergänzt es stabile Überschriftenanker und baut das Inhaltsverzeichnis;
stellt es MPF-only Markdown voran, sofern vorhanden;
löst es kanonische, MPF-, Identitäts-, Sprach- und Provenance-Metadaten auf;
stellt es einen Companion-Instruction-Block voran, wenn konfiguriert;
serialisiert es das MPF-Dokument und schreibt es in den Ausgabebaum;
schreibt es eine Signatur neben das MPF-Dokument, wenn Signing konfiguriert ist.

Das Ausgabeverzeichnis ist standardmäßig das Quellverzeichnis und kann mit --out überschrieben werden.

3. Frontmatter

3.1 Für eine Seite ausgegebene Felder

Der aktuelle Seitengenerator gibt folgende Felder aus:

Feld	Verhalten
`mpf`	MPF-Version aus der Site-Konfiguration.
`title`	HTML-Seitentitel. Erforderlich.
`url`	Kanonische menschenlesbare URL. Erforderlich.
`mpf-url`	Absolute URL dieser MPF-Datei.
`organization`	Organisation aus der Site-Konfiguration.
`domain`	Domain aus der Site-Konfiguration.
`lang`	Sprache aus Seiten-Override, sonst aus dem Pfad abgeleitet, sonst Standardsprache.
`updated`	Änderungsdatum der Quell-HTML-Datei im Format `YYYY-MM-DD`.
`author`	Autor aus der Site-Konfiguration.
`provenance`	Seiten-Override oder konfigurierter Standard. Erforderlich.
`source-hash`	SHA-256 des rohen Quell-HTML.
`toc`	Array erzeugter Überschriftseinträge.
`spec-origin`	Konfigurierter Spec-Origin, sonst konfigurierte Domain.
`content-origin`	Konfigurierter Content-Origin, sonst konfigurierte Domain.
`content-id`	Seiten-Override oder erzeugte stabile Content-Identität. Erforderlich.
`content-parity`	Beziehung zwischen MPF-Inhalt und menschenlesbarem HTML.
`mpf-id`	SHA-256-Identifikator der erzeugten MPF-Repräsentation.

Die Implementierung kann außerdem folgende optionale Felder ausgeben, wenn sie zu einem nicht leeren Wert aufgelöst werden:

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

Der Builder bricht mit einem Fehler ab, wenn der Seite Titel, kanonische URL, Provenance oder Content ID fehlen.

3.2 Summary

summary wird in dieser Reihenfolge aufgelöst:

Seiten-Override summary;
HTML-Metadatenbeschreibung;
weggelassen.

3.3 Content parity

Enthält das HTML MPF-only Material, das die Implementierung erkennt, wird das Seiten-Frontmatter auf Folgendes gesetzt:

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

Andernfalls verwendet content-parity den konfigurierten Standard. Ist kein Standard konfiguriert, verwendet die Implementierung:

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

4. URLs und Identität

4.1 Kanonische URL

Liefert die Seitenmetadaten eine kanonische URL, wird diese gegen die konfigurierte Base URL aufgelöst und verwendet. Bei einer index.html-Seite wird der kanonische Pfad so normalisiert, dass er mit / endet.

Ohne kanonische Seitenmetadaten:

wird das Root-index.html zur normalisierten Base URL plus / aufgelöst;
werden andere HTML-Pfade unterhalb der konfigurierten Base URL aufgelöst, nachdem ein abschließendes index.html entfernt wurde.

4.2 Content ID

Die erzeugte Seitenidentität hat folgende Form:

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

Der konfigurierte Locale-Präfix wird vor der Slug-Erzeugung entfernt, sodass Übersetzungen derselben Route dieselbe erzeugte Content ID erhalten.

Der Slug der Root-Seite ist home.

Bei Nicht-Root-Seiten wird die Route kleingeschrieben, Pfadsegmente werden mit Bindestrichen verbunden und nicht unterstützte Zeichen zu Bindestrichen normalisiert.

Beispiel aus der ESFI-Implementierung:

esfi:page:home

4.3 Spracherkennung

Konfigurierte Sprachen stammen aus config.languages. Ist diese Liste leer oder nicht vorhanden, wird nur die konfigurierte Standardsprache verwendet.

Der Builder prüft das erste Pfadsegment. Ist es ein konfigurierter Sprachcode, wird diese Sprache zugewiesen; andernfalls die Standardsprache.

4.4 Sprachvarianten

Für jede konfigurierte Sprache erzeugt der Builder einen language-variants-Eintrag, der auf die erwartete MPF-URL für denselben locale-unabhängigen Inhaltspfad zeigt.

Für die Standardsprache wird kein Locale-Pfadpräfix eingefügt. Nichtstandardvarianten erhalten /<lang>/.

Die Implementierung erzeugt diese URLs aus Konfiguration und Pfadidentität; sie prüft in diesem Schritt nicht, ob jede übersetzte Datei existiert.

Beispiel:

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. Markdown-Body und Inhaltsverzeichnis

Der ausgewählte HTML-Inhalt wird vor der MPF-Serialisierung in Markdown konvertiert.

Überschriften H1 bis H4 werden in toc aufgenommen und erhalten explizite Markdown-Anker:

## Example heading {#example-heading}

Jeder TOC-Eintrag hat:

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

Die Ankererzeugung:

schreibt die Überschrift klein;
behält Unicode-Buchstaben und -Zahlen;
ersetzt andere Folgen durch -;
fasst wiederholte Bindestriche zusammen;
entfernt führende und abschließende Bindestriche;
fällt auf section zurück, wenn kein Slug übrig bleibt;
löst Duplikate durch Anhängen von -2, -3 usw. auf.

Überschriften innerhalb von fenced code blocks werden ignoriert.

Bestehende Inline-Markdown-Formatierung und Links werden aus dem Überschriftentext entfernt, der für die TOC-Identität verwendet wird.

6. Companion instruction

Wenn companion-instruction vorhanden ist, stellt der Builder sie dem Markdown-Body als Blockquote voran.

Einzeilige Form:

> Companion instruction: <instruction>

Mehrzeilige Form:

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

7. Site-Indizes

Ein Build erzeugt außerdem drei Discovery-Ausgaben auf Site-Ebene:

llms.mpf
llms.txt
llms-full.txt

7.1 Indexierte Seiten

Eine Seite wird nur in erzeugte Indizes aufgenommen, wenn ihr aufgelöstes Frontmatter Folgendes enthält:

index: true

Indexierte Einträge werden lexikografisch nach MPF-URL sortiert.

7.2 llms.mpf

llms.mpf ist selbst ein MPF-0.6-Dokument. Sein erzeugtes Frontmatter verwendet:

Titel Site Index — <organization>;
Sprache = konfigurierte Standardsprache;
Provenance = human;
Content Type = reference;
index: true;
content-id: <content-id-prefix>:page:llms;
verborgene/Nicht-HTML Content Parity.

Sein Body enthält die Organisationsüberschrift, eine optionale konfigurierte Beschreibung und eine Markdown-Liste aller indexierten MPF-Seiten. Jeder Eintrag enthält die Summary der Seite, sofern vorhanden.

Die Implementierung dieser Version nimmt indexierte Seiten aus allen konfigurierten Sprachen in llms.mpf auf.

7.3 llms.txt

Der Builder pflegt einen MPF-Discovery-Abschnitt in llms.txt:

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

## Pages
...

Existiert kein llms.txt, erzeugt der Builder eines mit einer Organisationsüberschrift. Existiert bereits ein MPF-Abschnitt, ersetzt er diesen Abschnitt und bewahrt den Inhalt davor und danach.

7.4 llms-full.txt

llms-full.txt verkettet nur die Bodies indexierter Seiten in der konfigurierten Standardsprache.

Für jede Seite schreibt es Titel, kanonische URL und erzeugten MPF-Body.

8. Signierung

Der Builder lädt einen Signing Key aus der konfigurierten Signing-Key-Einstellung.

Wenn ein Signing Key verfügbar ist:

erhält das Seiten-Frontmatter eine signature-URL;
erhält llms.mpf ebenfalls eine signature-URL;
schreibt die Implementierung ein Signatur-Artefakt neben den erzeugten MPF-Inhalt.

Ist kein Signing Key konfiguriert, wird das Feld signature weggelassen.

9. Kommandozeilenschnittstelle

Die implementierte CLI lautet:

mpf-build <source-dir> [options]

Optionen:

Option	Wirkung
`--config <path>`	Eine bestimmte `mpf.config.json` verwenden.
`--out <path>`	Erzeugte Dateien in ein anderes Verzeichnis schreiben.
`--dry-run`	Erzeugte Pfade melden, ohne Dateien zu schreiben.
`--verbose`	Jede verarbeitete Datei mit Titel, URL und TOC-Anzahl protokollieren.
`--watch`	Bei Änderungen an HTML, Seiten-Override oder Konfiguration neu bauen.

Im Watch-Modus werden Rebuild-Anforderungen serialisiert: Tritt während eines laufenden Builds eine Änderung auf, wird genau ein weiterer Rebuild in die Warteschlange gestellt und anschließend ausgeführt.

10. ESFI-0.6-Referenzkonfiguration

Das ESFI-0.6-Deployment verwendete:

{
  "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"
}

Dieses Deployment definierte außerdem Standardwerte für Provenance, Confidence, Content Type, Indexierung, Companion Scope, Companion Contact, Preferred Representation und Content Parity.

11. Nicht-Behauptungen

MPF 0.6 erhält nicht allein deshalb eine Fähigkeit, weil ein Feldname sie beschreiben könnte. Diese Spezifikation beansprucht nur Verhalten, das in der zugehörigen Referenzimplementierung vorhanden ist.

Insbesondere sind erzeugte Metadaten wie language-variants, confidence, companion-scope, valid-until oder review-after beschreibende Metadaten. Der Builder gibt oder leitet sie wie oben beschrieben ab; die 0.6-Implementierung impliziert keine zusätzliche Policy Engine, Netzwerkvalidierung, Übersetzungsprüfung, Ablaufdurchsetzung oder Confidence-Berechnung.