Machine Page Format (MPF) 0.7

Status: implemented specification
Version: 0.7
Reference implementation: mpf-build

Machine Page Format (MPF) is a generated, machine-readable companion representation of a web page. MPF 0.7 is defined here by the behavior of the current mpf-build implementation. This document describes what the implementation produces; it does not define unimplemented future behavior.

1. File form

An MPF document is UTF-8 text with YAML frontmatter followed by a Markdown body.

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

# Markdown body

The frontmatter is serialized with stable insertion order. The body is trimmed before serialization and the final document ends with a newline.

1.1 MPF identifier

mpf-id is a SHA-256 digest of the complete generated MPF document before the mpf-id field itself is inserted.

The digest source is exactly:

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

<body>

This makes mpf-id a content identifier for the generated MPF representation, not for the source HTML.

1.2 Source hash

source-hash is a SHA-256 digest of the raw source HTML read by mpf-build.

2. Page generation

mpf-build walks the source directory recursively, ignores hidden entries and node_modules, and processes files ending in .html or .htm.

For each page it:

1. reads the raw HTML and file modification time;
2. loads the site configuration and any page override;
3. parses page metadata;
4. extracts MPF-only material and applies the MPF HTML transformations used by the implementation;
5. selects the configured content region;
6. strips non-content noise;
7. converts the selected HTML to Markdown;
8. adds stable heading anchors and builds the table of contents;
9. prepends MPF-only Markdown, if present;
10. resolves canonical, MPF, identity, language and provenance metadata;
11. prepends a companion instruction block when configured;
12. serializes the MPF document and writes it to the output tree;
13. writes a signature alongside the MPF document when signing is configured.

The output directory defaults to the source directory and can be overridden with --out.

3. Frontmatter

3.1 Fields emitted for a page

The current page generator emits these fields:

The implementation can also emit the following optional fields when they resolve to a non-empty value:

• 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

The builder stops with an error if the page has no title, canonical URL, provenance, or content ID.

3.2 Summary

summary resolves in this order:

1. page override summary;
2. HTML metadata description;
3. omitted.

3.3 Content parity

If the HTML contains MPF-only material detected by the implementation, page frontmatter is forced to:

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

Otherwise, content-parity uses the configured default. If no default is configured, the implementation uses:

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

4. URLs and identity

4.1 Canonical URL

If page metadata provides a canonical URL, that URL is resolved against the configured base URL and used. For an index.html page, the canonical pathname is normalized to end in /.

Without page canonical metadata:

• root index.html resolves to the normalized base URL plus /;
• other HTML paths resolve beneath the configured base URL after removing a terminal index.html.

4.2 Content ID

Generated page identity has this form:

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

The configured locale prefix is removed before the slug is generated, so translations of the same route receive the same generated content ID.

The root page slug is home.

For non-root pages, the route is lowercased, path segments are joined with hyphens, and unsupported characters are normalized to hyphens.

Example from the ESFI implementation:

esfi:page:home

4.3 Language detection

Configured languages come from config.languages. If that list is empty or absent, only the configured default language is used.

The builder checks the first path segment. If it is a configured language code, that language is assigned; otherwise the default language is assigned.

4.4 Language variants

For every configured language, the builder generates a language-variants entry pointing to the expected MPF URL for the same locale-independent content path.

For the default language, no locale path prefix is inserted. Non-default variants receive /<lang>/.

The implementation generates these URLs from configuration and path identity; it does not check in this step whether every translated file exists.

Example:

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 and table of contents

The selected HTML content is converted to Markdown before MPF serialization.

Headings at levels H1 through H4 are included in toc and receive explicit Markdown anchors:

## Example heading {#example-heading}

Each TOC entry has:

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

Anchor generation:

• lowercases the heading;
• keeps Unicode letters and numbers;
• replaces other runs with -;
• collapses repeated hyphens;
• trims leading and trailing hyphens;
• falls back to section if no slug remains;
• resolves duplicates by appending -2, -3, and so on.

Headings inside fenced code blocks are ignored.

Existing inline Markdown formatting and links are removed from the heading text used for TOC identity.

6. Companion instruction

If companion-instruction is present, the builder prepends it to the Markdown body as a blockquote.

Single-line form:

> Companion instruction: <instruction>

Multiline form:

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

6.1 Companion footer

If companion-footer is present, the builder appends it to the Markdown body after all page content, separated from the preceding body by one blank line. The value is also emitted as the companion-footer frontmatter field.

The footer is a publisher signature: the organisation name, optionally with its URL. It is plain text / Markdown on a single line and must not contain HTML. It is explicitly not a promotional or advertising field.

A site may set defaults.companion-footer; a page may override it with companion-footer in its .mpf.json file. If neither is configured, no footer line or companion-footer frontmatter field is emitted.

Generic example:

Example Publisher — https://example.org

7. Site indexes

A build also produces three site-level discovery outputs:

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

7.1 Indexed pages

A page is included in generated indexes only when its resolved frontmatter has:

index: true

Indexed entries are sorted lexicographically by MPF URL.

7.2 llms.mpf

llms.mpf is itself an MPF 0.7 document. Its generated frontmatter uses:

• title Site Index — <organization>;
• language = configured default language;
• provenance = human;
• content type = reference;
• index: true;
• content-id: <content-id-prefix>:page:llms;
• hidden/non-HTML content parity.

Its body contains the organization heading, optional configured description, and a Markdown list of all indexed MPF pages. Each item includes the page summary when available.

The current implementation includes indexed pages from all configured languages in llms.mpf.

7.3 llms.txt

The builder maintains an MPF discovery section in llms.txt:

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

## Pages
...

MPF-spec is emitted when spec-url is configured. spec-url is the canonical specification page for the version declared by mpf; publishers should update the two together when changing format versions.

If no llms.txt exists, it creates one with an organization heading. If a previous MPF section exists, it replaces that section while preserving content before and after it.

7.4 llms-full.txt

llms-full.txt concatenates the bodies of indexed pages in the configured default language only.

For each page it writes the title, canonical URL, and generated MPF body.

8. Signing

The builder loads a signing key from the configured signing-key setting.

When a signing key is available:

• page frontmatter receives a signature URL;
• llms.mpf also receives a signature URL;
• the implementation writes a signature artifact alongside generated MPF content.

When no signing key is configured, the signature field is omitted.

9. Command-line interface

The implemented CLI is:

mpf-build <source-dir> [options]

Options:

In watch mode, rebuild requests are serialized: if a change occurs during a running build, one queued rebuild runs afterward.

10. 0.7 configuration example

A 0.7 publisher configuration can declare the canonical specification pointer and a default publisher footer alongside the existing settings:

{
  "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 supplies the MPF-spec discovery line. defaults.companion-footer supplies the publisher signature unless a page overrides it.

11. Changelog

0.7

MPF 0.7 adds exactly two format capabilities to 0.6:

1. companion-footer: a configurable publisher signature emitted in frontmatter and appended as the final one-line Markdown body element, with per-page override support.
2. MPF-spec in the generated llms.txt discovery section, sourced from the configured spec-url, so machines can reach the canonical specification for the declared MPF version without guessing.

All MPF 0.6 fields, ordering, identity rules, and other generation behavior remain unchanged.

12. Non-claims

MPF 0.7 does not gain a capability merely because a field name could describe it. This specification only claims behavior present in the reference implementation.

In particular, generated metadata such as language-variants, confidence, companion-scope, valid-until, or review-after is descriptive metadata. The builder emits or derives it as described above; no additional policy engine, network validation, translation verification, expiry enforcement, or confidence calculation is implied by the 0.7 implementation.