Machine Page Format (MPF) 0.7

Status: geïmplementeerde specificatie
Versie: 0.7
Referentie-implementatie: mpf-build

Machine Page Format (MPF) is een gegenereerde, machineleesbare companion-representatie van een webpagina. MPF 0.7 wordt hier bepaald door het gedrag van de huidige mpf-build-implementatie. Dit document beschrijft wat de implementatie produceert; het definieert geen toekomstig gedrag dat nog niet is geïmplementeerd.

1. Bestandsvorm

Een MPF-document is UTF-8-tekst met YAML-frontmatter gevolgd door een Markdown-body.

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

# Markdown body

De frontmatter wordt geserialiseerd in stabiele invoegvolgorde. De body wordt vóór serialisatie getrimd en het uiteindelijke document eindigt met een newline.

1.1 MPF-identifier

mpf-id is een SHA-256-hash van het volledige gegenereerde MPF-document voordat het veld mpf-id zelf wordt toegevoegd.

De hashbron is exact:

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

<body>

Daarmee is mpf-id een contentidentifier voor de gegenereerde MPF-representatie, niet voor de bron-HTML.

1.2 Bronhash

source-hash is een SHA-256-hash van de ruwe bron-HTML die mpf-build leest.

2. Paginageneratie

mpf-build doorloopt de bronmap recursief, negeert verborgen items en node_modules, en verwerkt bestanden die eindigen op .html of .htm.

Voor elke pagina:

1. leest het de ruwe HTML en de wijzigingstijd van het bestand;
2. laadt het de siteconfiguratie en eventuele page override;
3. parseert het de paginametadata;
4. haalt het MPF-only materiaal uit de pagina en past het de MPF-HTML-transformaties van de implementatie toe;
5. selecteert het het geconfigureerde contentgebied;
6. verwijdert het ruis die niet tot de content behoort;
7. converteert het de geselecteerde HTML naar Markdown;
8. voegt het stabiele heading-ankers toe en bouwt het de inhoudsopgave;
9. plaatst het MPF-only Markdown vooraan, indien aanwezig;
10. bepaalt het canonical-, MPF-, identiteits-, taal- en provenancemetadata;
11. plaatst het een companion instruction-blok vooraan wanneer geconfigureerd;
12. serialiseert het het MPF-document en schrijft het naar de outputtree;
13. schrijft het een signature naast het MPF-document wanneer signing is geconfigureerd.

De outputmap is standaard de bronmap en kan met --out worden gewijzigd.

3. Frontmatter

3.1 Velden die voor een pagina worden uitgestuurd

De huidige paginagenerator stuurt de volgende velden uit:

De implementatie kan daarnaast de volgende optionele velden uitsturen wanneer ze naar een niet-lege waarde resolven:

• 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

De builder stopt met een fout als de pagina geen titel, canonical URL, provenance of content ID heeft.

3.2 Samenvatting

summary wordt in deze volgorde bepaald:

1. page override summary;
2. HTML-metadatabeschrijving;
3. weggelaten.

3.3 Content parity

Als de HTML MPF-only materiaal bevat dat de implementatie detecteert, wordt de page frontmatter geforceerd naar:

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

Anders gebruikt content-parity de geconfigureerde standaard. Als geen standaard is geconfigureerd, gebruikt de implementatie:

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

4. URL’s en identiteit

4.1 Canonieke URL

Als paginametadata een canonical URL levert, wordt die tegen de geconfigureerde base URL opgelost en gebruikt. Voor een index.html-pagina wordt het canonical pad genormaliseerd zodat het op / eindigt.

Zonder canonical paginametadata:

• resolveert root index.html naar de genormaliseerde base URL plus /;
• resolven andere HTML-paden onder de geconfigureerde base URL nadat een afsluitende index.html is verwijderd.

4.2 Content ID

Gegenereerde pagina-identiteit heeft deze vorm:

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

De geconfigureerde locale-prefix wordt verwijderd vóór de slug wordt gegenereerd, zodat vertalingen van dezelfde route hetzelfde gegenereerde content ID krijgen.

De slug van de rootpagina is home.

Voor niet-rootpagina’s wordt de route naar lowercase omgezet, worden padsegmenten met koppeltekens verbonden en worden niet-ondersteunde tekens naar koppeltekens genormaliseerd.

Voorbeeld uit de ESFI-implementatie:

esfi:page:home

4.3 Taaldetectie

Geconfigureerde talen komen uit config.languages. Als die lijst leeg of afwezig is, wordt alleen de geconfigureerde standaardtaal gebruikt.

De builder controleert het eerste padsegment. Is dat een geconfigureerde taalcode, dan wordt die taal toegewezen; anders wordt de standaardtaal toegewezen.

4.4 Taalvarianten

Voor elke geconfigureerde taal genereert de builder een language-variants-item dat naar de verwachte MPF-URL voor hetzelfde locale-onafhankelijke contentpad wijst.

Voor de standaardtaal wordt geen locale-padprefix ingevoegd. Niet-standaardvarianten krijgen /<lang>/.

De implementatie genereert deze URL’s uit configuratie en padidentiteit; in deze stap controleert ze niet of elk vertaald bestand bestaat.

Voorbeeld:

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 en inhoudsopgave

De geselecteerde HTML-content wordt vóór MPF-serialisatie naar Markdown geconverteerd.

Headings H1 tot en met H4 worden in toc opgenomen en krijgen expliciete Markdown-ankers:

## Example heading {#example-heading}

Elke TOC-entry heeft:

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

Ankergeneratie:

• zet de heading om naar lowercase;
• behoudt Unicode-letters en -cijfers;
• vervangt andere reeksen door -;
• reduceert herhaalde koppeltekens;
• verwijdert koppeltekens aan begin en einde;
• valt terug op section als geen slug overblijft;
• lost duplicaten op door -2, -3 enzovoort toe te voegen.

Headings binnen fenced code blocks worden genegeerd.

Bestaande inline Markdown-opmaak en links worden verwijderd uit de headingtekst die voor TOC-identiteit wordt gebruikt.

6. Companion instruction

Als companion-instruction aanwezig is, plaatst de builder die als blockquote vooraan in de Markdown-body.

Eénregelige vorm:

> Companion instruction: <instruction>

Meerregelige vorm:

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

6.1 Companion footer

Als companion-footer aanwezig is, voegt de builder die na alle paginacontent toe aan de Markdown-body, gescheiden van de voorafgaande body door één lege regel. De waarde wordt ook als companion-footer-frontmatterveld uitgestuurd.

De footer is een uitgeverssignatuur: de naam van de organisatie, eventueel met URL. Het is platte tekst of Markdown op één regel en mag geen HTML bevatten. Het is expliciet geen promotioneel of advertentieveld.

Een site kan defaults.companion-footer instellen; een pagina kan die overschrijven met companion-footer in haar .mpf.json-bestand. Als geen van beide is geconfigureerd, wordt geen footerregel en geen companion-footer-frontmatterveld uitgestuurd.

Generiek voorbeeld:

Example Publisher — https://example.org

7. Site-indexen

Een build produceert ook drie discoveryoutputs op siteniveau:

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

7.1 Geïndexeerde pagina’s

Een pagina wordt alleen in gegenereerde indexen opgenomen wanneer de resolved frontmatter bevat:

index: true

Geïndexeerde entries worden lexicografisch op MPF-URL gesorteerd.

7.2 llms.mpf

llms.mpf is zelf een MPF 0.7-document. De gegenereerde frontmatter gebruikt:

• titel Site Index — <organization>;
• taal = geconfigureerde standaardtaal;
• provenance = human;
• content type = reference;
• index: true;
• content-id: <content-id-prefix>:page:llms;
• verborgen/niet-HTML content parity.

De body bevat de heading van de organisatie, een optionele geconfigureerde beschrijving en een Markdown-lijst van alle geïndexeerde MPF-pagina’s. Elk item bevat de paginasamenvatting wanneer beschikbaar.

De huidige implementatie neemt geïndexeerde pagina’s uit alle geconfigureerde talen op in llms.mpf.

7.3 llms.txt

De builder onderhoudt een MPF-discoverysectie in llms.txt:

MPF: <version>
MPF-spec: <canonical specification URL>
MPF-index: /llms.mpf

## Pages
...

MPF-spec wordt uitgestuurd wanneer spec-url is geconfigureerd. spec-url is de canonieke specificatiepagina voor de versie die door mpf wordt gedeclareerd; publishers moeten beide samen bijwerken wanneer ze van formaatversie veranderen.

Bestaat geen llms.txt, dan maakt de builder er een met een organisatieheading. Bestaat al een MPF-sectie, dan vervangt hij die sectie terwijl content ervoor en erna behouden blijft.

7.4 llms-full.txt

llms-full.txt concateneert alleen de bodies van geïndexeerde pagina’s in de geconfigureerde standaardtaal.

Per pagina schrijft het de titel, canonical URL en gegenereerde MPF-body.

8. Ondertekening

De builder laadt een signing key uit de geconfigureerde signing-key-instelling.

Wanneer een signing key beschikbaar is:

• krijgt page frontmatter een signature-URL;
• krijgt llms.mpf eveneens een signature-URL;
• schrijft de implementatie een signature-artifact naast de gegenereerde MPF-content.

Als geen signing key is geconfigureerd, wordt het signature-veld weggelaten.

9. Command-line interface

De geïmplementeerde CLI is:

mpf-build <source-dir> [options]

Opties:

In watchmodus worden rebuildverzoeken geserialiseerd: als tijdens een actieve build een wijziging optreedt, wordt één extra rebuild in de wachtrij gezet en daarna uitgevoerd.

10. Voorbeeld van 0.7-configuratie

Een publisherconfiguratie voor 0.7 kan naast de bestaande instellingen de canonieke specificatieverwijzing en een standaard uitgeversfooter declareren:

{
  "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 levert de MPF-spec-discoveryregel. defaults.companion-footer levert de uitgeverssignatuur tenzij een pagina die overschrijft.

11. Changelog

0.7

MPF 0.7 voegt precies twee formatcapaciteiten toe aan 0.6:

1. companion-footer: een configureerbare uitgeverssignatuur die in frontmatter wordt uitgestuurd en als laatste eenregelige Markdown-element aan de body wordt toegevoegd, met override per pagina.
2. MPF-spec in de gegenereerde llms.txt-discoverysectie, afkomstig van de geconfigureerde spec-url, zodat machines de canonieke specificatie voor de gedeclareerde MPF-versie kunnen bereiken zonder te gokken.

Alle MPF 0.6-velden, ordening, identiteitsregels en overige generatiegedrag blijven ongewijzigd.

12. Niet-claims

MPF 0.7 krijgt niet automatisch een capaciteit alleen omdat een veldnaam die zou kunnen beschrijven. Deze specificatie claimt uitsluitend gedrag dat in de referentie-implementatie aanwezig is.

Met name gegenereerde metadata zoals language-variants, confidence, companion-scope, valid-until of review-after zijn beschrijvende metadata. De builder stuurt of leidt ze af zoals hierboven beschreven; de 0.7-implementatie impliceert geen aanvullende policy engine, netwerkvalidatie, vertaalverificatie, expiry enforcement of confidence-berekening.