Implementation

From an existing static site to published MPF, in one build step.

MPF is generated, not hand-written. The reference implementation, mpf-build, reads a site’s finished HTML and writes a .mpf companion beside every page, together with the site’s machine indexes. Nothing changes in production: the server keeps serving static files.

This page is the implementation guide. Field definitions live in Specification 0.7; discovery is covered in Publishing and discovery. Every rule below is marked Specification 0.7, Reference implementation or ESFI practice; the markers are explained in the Overview.

Requirements

• A site that produces static HTML files (any generator, or hand-written HTML).
• Node.js 18 or later to run mpf-build. Reference implementation
• Write access to the output directory, and to DNS if you publish the optional DNS declaration.

1. Get the reference implementation

mpf-build is published as source at git.esfi.eu/esfi/mpf. It is not currently distributed through the npm registry.

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

Run it directly:

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

or make the mpf-build command available on your machine with npm link from the same directory.

2. Declare the publisher: mpf.config.json

The configuration file states who the publisher is, which languages the site uses, and the default declarations every page carries. It usually lives in the project root.

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

Required keys

The builder stops with an error if any of these is missing or invalid. Reference implementation

Optional keys

Every declaration is a publisher decision. Treat the defaults as a statement your organisation will stand behind, not as technical settings.

companion-scope records processing intent only. MPF does not carry licensing terms, pricing or compensation conditions; those belong to licensing mechanisms outside the format.

3. Override per page

Any page can override site defaults with a JSON sidecar beside its HTML file: index.html → index.mpf.json, guide/page.html → guide/page.mpf.json. Specification 0.7 (existence), Reference implementation (allowed fields)

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

Allowed override fields: 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.

An unknown field stops the build. related is an array of { "url", "relation" }, where relation is one of prerequisite, extends, source, contradicts, alternative, supersedes, details. Reference implementation

4. Control what goes into the body

Content region

The builder takes the element matched by content-selector. If nothing matches, or the match is empty, it falls back in order to main, article, [role="main"], .content and body. Inside the selected region it removes navigation, headers, footers, scripts, styles and elements marked aria-hidden="true". A page with no usable content region is skipped and reported. Specification 0.7 (content selection), Reference implementation (fallback order and noise list)

In-page markers

Four HTML attributes let a publisher control the machine body without changing what people see. Reference implementation

data-mpf-only is the one to use sparingly. Machine-only content is exactly what the parity declaration exists to make visible; the builder declares it automatically so it cannot be hidden.

5. Run the build last

Run mpf-build after the HTML is final, over the finished output directory:

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

Pass --config explicitly when processing a generated directory such as dist/, so the builder does not look for the configuration inside it. Reference implementation

Command-line options

Specification 0.7

What the build writes

Canonical URLs and source-hash values are always derived from the source HTML and its source-relative path, never from the output path. Reference implementation

Ordering and drift

Each companion pins its source with source-hash. If the HTML is regenerated without re-running mpf-build, or the reverse, the pair drifts. A stale companion is worse than a missing one, because it looks authoritative. Keep MPF generation as the last step of the build and deploy both representations together.

6. Sign (optional)

When signing-key points to a private key file, the builder signs every page companion and llms.mpf, writes the signature base64-encoded to a .sig file beside it, and adds a signature URL to the frontmatter. If the key file is missing, the build continues without signatures and prints a warning. Specification 0.7 (signature field and artifact), Reference implementation (encoding and key handling)

The signature covers the complete MPF file as written. Publish the corresponding public key where readers can find it, and state which algorithm it uses. The key never belongs in the repository or the output directory.

7. Publish discovery

The build produces llms.txt and llms.mpf. ESFI sites also publish a DNS TXT record, a /.well-known/mpf declaration and, optionally, a page-level alternate link. These are ESFI practice; how to set them up is described in Publishing and discovery.

8. Verify

Check what you published, not what you configured:

curl -s https://example.org/index.mpf | head -30     # companion exists and parses
curl -s https://example.org/llms.mpf | head -30      # index exists and lists pages
curl -s https://example.org/llms.txt                 # MPF section, MPF-spec, MPF-index
curl -s https://example.org/.well-known/mpf          # ESFI practice
dig +short TXT _mpf.example.org                      # ESFI practice

Then check the relationship between the two representations:

1. Drift. Compute the SHA-256 of the served HTML and compare it with source-hash. A mismatch means the pair is out of step, unless the server alters HTML in transit.
2. Identity. url must be the canonical human page; mpf-url must be the address you fetched.
3. Languages. For each entry in language-variants, confirm the file exists. The builder generates these addresses from configuration and does not check them.
4. Parity. If hidden-sections is true, read the machine-only content and make sure you intend it.
5. Scope. Confirm that companion-scope in the files, /.well-known/mpf and the DNS record state the same values.

Once your output can be inspected and matches a published version, it can be listed in the Implementation registry.

Troubleshooting

Specification: Specification 0.7 · Discovery: Publishing and discovery · Source: git.esfi.eu/esfi/mpf