Implementatie

Van een bestaande statische site naar gepubliceerde MPF, in één buildstap.

MPF wordt gegenereerd, niet met de hand geschreven. De referentie-implementatie, mpf-build, leest de voltooide HTML van een site en schrijft naast elke pagina een .mpf-companion, samen met de machine-indexen van de site. In productie verandert niets: de server blijft statische bestanden serveren.

Deze pagina is de implementatiehandleiding. Velddefinities staan in Specificatie 0.7; discovery wordt behandeld in Publicatie en discovery. Elke regel hieronder is gemarkeerd als Specificatie 0.7, Referentie-implementatie of ESFI-praktijk; de markers worden uitgelegd in het Overzicht.

Vereisten

• Een site die statische HTML-bestanden produceert (ongeacht generator, of handgeschreven HTML).
• Node.js 18 of nieuwer om mpf-build uit te voeren. Referentie-implementatie
• Schrijftoegang tot de outputmap, en tot DNS als u de optionele DNS-declaratie publiceert.

1. Haal de referentie-implementatie op

mpf-build wordt als bron gepubliceerd op git.esfi.eu/esfi/mpf. Het wordt momenteel niet via het npm-register verspreid.

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

Voer het rechtstreeks uit:

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

of maak het commando mpf-build beschikbaar op uw machine met npm link vanuit dezelfde map.

2. Declareer de uitgever: mpf.config.json

Het configuratiebestand vermeldt wie de uitgever is, welke talen de site gebruikt en welke standaarddeclaraties elke pagina draagt. Het staat doorgaans in de projectroot.

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

Verplichte keys

De builder stopt met een fout wanneer een van deze ontbreekt of ongeldig is. Referentie-implementatie

Optionele keys

Elke declaratie is een beslissing van de uitgever. Behandel de defaults als een verklaring waar uw organisatie achter zal staan, niet als technische instellingen.

companion-scope legt alleen processing intent vast. MPF bevat geen licentievoorwaarden, prijzen of compensatievoorwaarden; die horen bij licentiemechanismen buiten het formaat.

3. Override per pagina

Elke pagina kan sitestandaarden overschrijven met een JSON-sidecar naast haar HTML-bestand: index.html → index.mpf.json, guide/page.html → guide/page.mpf.json. Specificatie 0.7 (bestaan), Referentie-implementatie (toegestane velden)

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

Toegestane overridevelden: 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.

Een onbekend veld stopt de build. related is een array van { "url", "relation" }, waarbij relation één van prerequisite, extends, source, contradicts, alternative, supersedes, details is. Referentie-implementatie

4. Bepaal wat in de body terechtkomt

Contentgebied

De builder neemt het element dat overeenkomt met content-selector. Als niets overeenkomt, of de match leeg is, valt hij in deze volgorde terug op main, article, [role="main"], .content en body. Binnen het geselecteerde gebied verwijdert hij navigatie, headers, footers, scripts, styles en elementen met aria-hidden="true". Een pagina zonder bruikbaar contentgebied wordt overgeslagen en gerapporteerd. Specificatie 0.7 (contentselectie), Referentie-implementatie (fallbackvolgorde en ruislijst)

Markers in de pagina

Vier HTML-attributen laten een uitgever de machinebody sturen zonder te veranderen wat mensen zien. Referentie-implementatie

data-mpf-only moet spaarzaam worden gebruikt. Machine-only content is precies waarvoor de pariteitsdeclaratie bestaat; de builder declareert die automatisch zodat ze niet verborgen gezag kan krijgen.

5. Voer de build als laatste uit

Voer mpf-build uit nadat de HTML definitief is, over de voltooide outputmap:

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

Geef --config expliciet door wanneer u een gegenereerde map zoals dist/ verwerkt, zodat de builder de configuratie niet daarin zoekt. Referentie-implementatie

Command-line opties

Specificatie 0.7

Wat de build schrijft

Canonieke URL’s en source-hash-waarden worden altijd uit de bron-HTML en het bronrelatieve pad afgeleid, nooit uit het outputpad. Referentie-implementatie

Volgorde en drift

Elke companion verankert zijn bron met source-hash. Als de HTML opnieuw wordt gegenereerd zonder mpf-build opnieuw te draaien, of omgekeerd, drijven beide uit elkaar. Een verouderde companion is erger dan een ontbrekende, omdat hij gezaghebbend lijkt. Houd MPF-generatie als laatste stap van de build en deploy beide representaties samen.

6. Ondertekenen (optioneel)

Wanneer signing-key naar een private-keybestand wijst, ondertekent de builder elke page companion en llms.mpf, schrijft de signature base64-gecodeerd naar een .sig-bestand ernaast en voegt een signature-URL aan de frontmatter toe. Als het keybestand ontbreekt, gaat de build zonder signatures door en print een waarschuwing. Specificatie 0.7 (signatureveld en artefact), Referentie-implementatie (encoding en key handling)

De signature dekt het volledige MPF-bestand zoals geschreven. Publiceer de bijbehorende public key waar lezers hem kunnen vinden en vermeld welk algoritme wordt gebruikt. De key hoort nooit in de repository of outputmap.

7. Publiceer discovery

De build produceert llms.txt en llms.mpf. ESFI-sites publiceren daarnaast een DNS TXT-record, een /.well-known/mpf-declaratie en optioneel een page-level alternate link. Dit is ESFI-praktijk; hoe u die instelt staat in Publicatie en discovery.

8. Verifieer

Controleer wat u hebt gepubliceerd, niet wat u hebt geconfigureerd:

curl -s https://example.org/index.mpf | head -30     # companion bestaat en kan worden geparsed
curl -s https://example.org/llms.mpf | head -30      # index bestaat en bevat pagina's
curl -s https://example.org/llms.txt                 # MPF-sectie, MPF-spec, MPF-index
curl -s https://example.org/.well-known/mpf          # ESFI-praktijk
dig +short TXT _mpf.example.org                      # ESFI-praktijk

Controleer daarna de relatie tussen beide representaties:

1. Drift. Bereken de SHA-256 van de geserveerde HTML en vergelijk die met source-hash. Een mismatch betekent dat het paar uit sync is, tenzij de server HTML tijdens transport wijzigt.
2. Identiteit. url moet de canonieke menselijke pagina zijn; mpf-url moet het adres zijn dat u hebt opgehaald.
3. Talen. Bevestig voor elke invoer in language-variants dat het bestand bestaat. De builder genereert deze adressen uit configuratie en controleert ze niet.
4. Pariteit. Als hidden-sections true is, lees de machine-only content en controleer dat u die bedoelt.
5. Scope. Bevestig dat companion-scope in de bestanden, /.well-known/mpf en het DNS-record dezelfde waarden vermelden.

Zodra uw output kan worden geïnspecteerd en overeenkomt met een gepubliceerde versie, kan hij in het Implementatieregister worden opgenomen.

Problemen oplossen

Specificatie: Specificatie 0.7 · Discovery: Publicatie en discovery · Bron: git.esfi.eu/esfi/mpf