Machine Page Format (MPF) 0.7

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

Machine Page Format (MPF) ist eine generierte, maschinenlesbare Companion-Repräsentation einer Webseite. MPF 0.7 wird hier durch das Verhalten der aktuellen mpf-build-Implementierung definiert. Dieses Dokument beschreibt, was die 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.7'
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:

1. liest es das rohe HTML und den Änderungszeitpunkt der Datei;
2. lädt es die Site-Konfiguration und ein etwaiges Seiten-Override;
3. parst es die Seitenmetadaten;
4. extrahiert es MPF-only Material und wendet die von der Implementierung verwendeten MPF-HTML-Transformationen an;
5. wählt es den konfigurierten Inhaltsbereich;
6. entfernt es Nicht-Inhaltsrauschen;
7. konvertiert es das ausgewählte HTML in Markdown;
8. ergänzt es stabile Überschriftenanker und baut das Inhaltsverzeichnis;
9. stellt es MPF-only Markdown voran, sofern vorhanden;
10. löst es kanonische, MPF-, Identitäts-, Sprach- und Provenance-Metadaten auf;
11. stellt es einen Companion-Instruction-Block voran, wenn konfiguriert;
12. serialisiert es das MPF-Dokument und schreibt es in den Ausgabebaum;
13. 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:

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-footer
• 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:

1. Seiten-Override summary;
2. HTML-Metadatenbeschreibung;
3. 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>

6.1 Companion footer

Wenn companion-footer vorhanden ist, hängt der Builder ihn nach dem gesamten Seiteninhalt an den Markdown-Body an, getrennt vom vorhergehenden Body durch eine Leerzeile. Der Wert wird außerdem als companion-footer-Frontmatterfeld ausgegeben.

Der Footer ist eine Herausgeber-Signatur: der Name der Organisation, optional mit ihrer URL. Er besteht aus einer einzigen Zeile Klartext oder Markdown und darf kein HTML enthalten. Er ist ausdrücklich kein Werbe- oder Promotionsfeld.

Eine Site kann defaults.companion-footer setzen; eine Seite kann ihn mit companion-footer in ihrer .mpf.json-Datei überschreiben. Ist beides nicht konfiguriert, werden weder Footerzeile noch companion-footer-Frontmatterfeld ausgegeben.

Generisches Beispiel:

Example Publisher — https://example.org

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.7-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 aktuelle Implementierung 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-spec: <canonical specification URL>
MPF-index: /llms.mpf

## Pages
...

MPF-spec wird ausgegeben, wenn spec-url konfiguriert ist. spec-url ist die kanonische Spezifikationsseite für die von mpf deklarierte Version; Publisher sollten beide gemeinsam aktualisieren, wenn sie die Formatversion wechseln.

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:

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. Beispiel für eine 0.7-Konfiguration

Eine 0.7-Publisher-Konfiguration kann neben den bestehenden Einstellungen den Zeiger auf die kanonische Spezifikation und einen standardmäßigen Herausgeber-Footer deklarieren:

{
  "mpf": "0.7",
  "organization": "Example Publisher",
  "domain": "example.org",
  "base-url": "https://example.org/",
  "spec-url": "https://docs.example.org/spec/mpf/0.7",
  "author": "Example Publisher",
  "default-lang": "en",
  "languages": ["en"],
  "content-id-prefix": "example",
  "defaults": {
    "provenance": "human",
    "index": true,
    "companion-footer": "Example Publisher — https://example.org"
  }
}

spec-url liefert die MPF-spec-Discovery-Zeile. defaults.companion-footer liefert die Herausgeber-Signatur, sofern eine Seite sie nicht überschreibt.

11. Changelog

0.7

MPF 0.7 ergänzt genau zwei Formatfähigkeiten gegenüber 0.6:

1. companion-footer: eine konfigurierbare Herausgeber-Signatur, die im Frontmatter ausgegeben und als letztes einzeiliges Markdown-Element an den Body angehängt wird, mit Override-Unterstützung pro Seite.
2. MPF-spec im erzeugten llms.txt-Discovery-Abschnitt, gespeist aus der konfigurierten spec-url, damit Maschinen die kanonische Spezifikation für die deklarierte MPF-Version ohne Raten erreichen.

Alle MPF-0.6-Felder, ihre Reihenfolge, Identitätsregeln und das übrige Generierungsverhalten bleiben unverändert.

12. Nicht-Behauptungen

MPF 0.7 erhält nicht allein deshalb eine Fähigkeit, weil ein Feldname sie beschreiben könnte. Diese Spezifikation beansprucht nur Verhalten, das in der 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.7-Implementierung impliziert keine zusätzliche Policy Engine, Netzwerkvalidierung, Übersetzungsprüfung, Ablaufdurchsetzung oder Confidence-Berechnung.