docs: add SEO frontmatter, llms.txt, and code-block hygiene

Add YAML frontmatter (title, description) to every English doc under
docs/*.md, rename generic headings (## Setup, ## Configuration, etc.)
to topic-specific ones, fix code-block language tags where wrong, and
add filename or purpose comments on blocks that represent a real file.

Add a root llms.txt index pointing AI agents at the canonical English
docs (Core Concepts, Setup and Build, Worker Mode and Extensions,
Frameworks, Real-Time and Performance, Production and Observability).

Translations under docs/<lang>/ are intentionally left untouched and
should be regenerated by running docs/translate.php.

Author: dunglas

docs/classic.md

@@ -1,3 +1,8 @@
+---
+title: FrankenPHP Classic Mode: Drop-in PHP-FPM Replacement
+description: Run FrankenPHP in classic mode as a drop-in replacement for PHP-FPM or Apache mod_php, with a fixed or autoscaling thread pool serving PHP files directly.
+---
+
 # Using Classic Mode
 
 Without any additional configuration, FrankenPHP operates in classic mode. In this mode, FrankenPHP functions like a traditional PHP server, directly serving PHP files. This makes it a seamless drop-in replacement for PHP-FPM or Apache with mod_php.

docs/compile.md

@@ -1,3 +1,8 @@
+---
+title: Compile FrankenPHP From Sources With PHP as a Library
+description: Build FrankenPHP from source on Linux, macOS and FreeBSD, link PHP as a dynamic library via xcaddy or go build, and add custom Caddy modules and extensions.
+---
+
 # Compile From Sources
 
 This document explains how to create a FrankenPHP binary that will load PHP as a dynamic library.
@@ -36,7 +41,7 @@ cd php-*/
 Then, run the `configure` script with the options needed for your platform.
 The following `./configure` flags are mandatory, but you can add others, for example, to compile extensions or additional features.
 
-#### Linux
+#### Linux and FreeBSD
 
 ```console
 ./configure \

docs/config.md

@@ -1,3 +1,8 @@
+---
+title: Configuring FrankenPHP With Caddyfile, php.ini, and Env Vars
+description: Configure FrankenPHP and Caddy via Caddyfile, JSON, or environment variables, including PHP runtime tuning, worker mode, file watching, and module options.
+---
+
 # Configuration
 
 FrankenPHP, Caddy as well as the [Mercure](mercure.md) and [Vulcain](https://vulcain.rocks) modules can be configured using [the formats supported by Caddy](https://caddyserver.com/docs/getting-started#your-first-config).
@@ -9,6 +14,7 @@ You can specify a custom path with the `-c` or `--config` option.
 A minimal `Caddyfile` to serve a PHP application is shown below:
 
 ```caddyfile
+# Caddyfile
 # The hostname to respond to
 localhost
 
@@ -39,6 +45,7 @@ PHP:
 - You should copy an official template provided by the PHP project:
 
 ```dockerfile
+# Dockerfile
 FROM dunglas/frankenphp
 
 # Production:
@@ -80,6 +87,7 @@ The `php_server` or the `php` [HTTP directives](https://caddyserver.com/docs/cad
 Minimal example:
 
 ```caddyfile
+# Caddyfile
 localhost {
 	# Enable compression (optional)
 	encode zstd br gzip
@@ -91,6 +99,7 @@ localhost {
 You can also explicitly configure FrankenPHP using the [global option](https://caddyserver.com/docs/caddyfile/concepts#global-options) `frankenphp`:
 
 ```caddyfile
+# Caddyfile
 {
 	frankenphp {
 		num_threads <num_threads> # Sets the number of PHP threads to start. Default: 2x the number of available CPUs.
@@ -116,6 +125,7 @@ You can also explicitly configure FrankenPHP using the [global option](https://c
 Alternatively, you may use the one-line short form of the `worker` option:
 
 ```caddyfile
+# Caddyfile
 {
 	frankenphp {
 		worker <file> <num>
@@ -128,6 +138,7 @@ Alternatively, you may use the one-line short form of the `worker` option:
 You can also define multiple workers if you serve multiple apps on the same server:
 
 ```caddyfile
+# Caddyfile
 app.example.com {
     root /path/to/app/public
 	php_server {
@@ -155,6 +166,7 @@ it's a PHP file or not. Read more about it in the [performance page](performance
 Using the `php_server` directive is equivalent to this configuration:
 
 ```caddyfile
+# Caddyfile
 route {
 	# Add trailing slash for directory requests
 	@canonicalPath {
@@ -178,6 +190,7 @@ route {
 The `php_server` and the `php` directives have the following options:
 
 ```caddyfile
+# Caddyfile
 php_server [<matcher>] {
 	root <directory> # Sets the root folder to the site. Default: `root` directive.
 	split_path <delim...> # Sets the substrings for splitting the URI into two parts. The first matching substring will be used to split the "path info" from the path. The first piece is suffixed with the matching substring and will be assumed as the actual resource (CGI script) name. The second piece will be set to PATH_INFO for the script to use. Default: `.php`
@@ -205,6 +218,7 @@ Workers can instead be restarted on file changes via the `watch` directive.
 This is useful for development environments.
 
 ```caddyfile
+# Caddyfile
 {
 	frankenphp {
 		worker {
@@ -223,6 +237,7 @@ where the FrankenPHP process was started. You can instead also specify one or mo
 [shell filename pattern](https://pkg.go.dev/path/filepath#Match):
 
 ```caddyfile
+# Caddyfile
 {
 	frankenphp {
 		worker {
@@ -254,6 +269,7 @@ The following example will always serve a file in the public directory if presen
 and otherwise forward the request to the worker matching the path pattern.
 
 ```caddyfile
+# Caddyfile
 {
 	frankenphp {
 		php_server {
@@ -278,14 +294,15 @@ But when the fix depends on a third party you don't control,
 `max_requests` provides a pragmatic and hopefully temporary workaround for production:
 
 ```caddyfile
+# Caddyfile
 {
 	frankenphp {
 		max_requests 500
 	}
 }
 ```
 
-## Environment Variables
+## FrankenPHP Environment Variables
 
 The following environment variables can be used to inject Caddy directives in the `Caddyfile` without modifying it:
 
@@ -298,7 +315,7 @@ As for FPM and CLI SAPIs, environment variables are exposed by default in the `$
 
 The `S` value of [the `variables_order` PHP directive](https://www.php.net/manual/en/ini.core.php#ini.variables-order) is always equivalent to `ES` regardless of the placement of `E` elsewhere in this directive.
 
-## PHP config
+## PHP Configuration in FrankenPHP
 
 To load [additional PHP configuration files](https://www.php.net/manual/en/configuration.file.php#configuration.file.scan),
 the `PHP_INI_SCAN_DIR` environment variable can be used.
@@ -307,6 +324,7 @@ When set, PHP will load all the file with the `.ini` extension present in the gi
 You can also change the PHP configuration using the `php_ini` directive in the `Caddyfile`:
 
 ```caddyfile
+# Caddyfile
 {
     frankenphp {
         php_ini memory_limit 256M
@@ -338,6 +356,7 @@ has been read. (for example: [Mercure](mercure.md), WebSocket, Server-Sent Event
 This is an opt-in configuration that needs to be added to the global options in the `Caddyfile`:
 
 ```caddyfile
+# Caddyfile
 {
   servers {
     enable_full_duplex

docs/docker.md

@@ -1,3 +1,8 @@
+---
+title: FrankenPHP Docker Image: Build, Configure, Extend
+description: Build custom FrankenPHP Docker images, install PHP extensions and Caddy modules, run as non-root, harden with distroless, and enable worker mode by default.
+---
+
 # Building Custom Docker Image
 
 [FrankenPHP Docker images](https://hub.docker.com/r/dunglas/frankenphp) are based on [official PHP images](https://hub.docker.com/_/php/).
@@ -13,11 +18,12 @@ The tags follow this pattern: `dunglas/frankenphp:<frankenphp-version>-php<php-v
 
 [Browse tags](https://hub.docker.com/r/dunglas/frankenphp/tags).
 
-## How to Use The Images
+## How to Use the FrankenPHP Docker Images
 
 Create a `Dockerfile` in your project:
 
 ```dockerfile
+# Dockerfile
 FROM dunglas/frankenphp
 
 COPY . /app/public
@@ -30,7 +36,7 @@ docker build -t my-php-app .
 docker run -it --rm --name my-running-app my-php-app
 ```
 
-## How to Tweak the Configuration
+## How to Tweak the FrankenPHP Docker Configuration
 
 For convenience, [a default `Caddyfile`](https://github.com/php/frankenphp/blob/main/caddy/frankenphp/Caddyfile) containing
 useful environment variables is provided in the image.
@@ -41,6 +47,7 @@ The [`docker-php-extension-installer`](https://github.com/mlocati/docker-php-ext
 Adding additional PHP extensions is straightforward:
 
 ```dockerfile
+# Dockerfile
 FROM dunglas/frankenphp
 
 # add additional extensions here:
@@ -59,6 +66,7 @@ FrankenPHP is built on top of Caddy, and all [Caddy modules](https://caddyserver
 The easiest way to install custom Caddy modules is to use [xcaddy](https://github.com/caddyserver/xcaddy):
 
 ```dockerfile
+# Dockerfile
 FROM dunglas/frankenphp:builder AS builder
 
 # Copy xcaddy in the builder image
@@ -99,6 +107,7 @@ The `builder` image provided by FrankenPHP contains a compiled version of `libph
 Set the `FRANKENPHP_CONFIG` environment variable to start FrankenPHP with a worker script:
 
 ```dockerfile
+# Dockerfile
 FROM dunglas/frankenphp
 
 # ...
@@ -154,6 +163,7 @@ FrankenPHP can run as non-root user in Docker.
 Here is a sample `Dockerfile` doing this:
 
 ```dockerfile
+# Dockerfile
 FROM dunglas/frankenphp
 
 ARG USER=appuser
@@ -179,6 +189,7 @@ If you expose FrankenPHP on a non-privileged port (1024 and above), it's possibl
 the webserver as a non-root user, and without the need for any capability:
 
 ```dockerfile
+# Dockerfile
 FROM dunglas/frankenphp
 
 ARG USER=appuser
@@ -198,14 +209,14 @@ USER ${USER}
 Next, set the `SERVER_NAME` environment variable to use an unprivileged port.
 Example: `:8000`
 
-## Updates
+## FrankenPHP Docker Image Updates
 
 The Docker images are built:
 
 - when a new release is tagged
 - daily at 4 am UTC, if new versions of the official PHP images are available
 
-## Hardening Images
+## Hardening FrankenPHP Docker Images
 
 To further reduce the attack surface and size of your FrankenPHP Docker images, it's also possible to build them on top of a
 [Google distroless](https://github.com/GoogleContainerTools/distroless) or
@@ -218,6 +229,7 @@ To further reduce the attack surface and size of your FrankenPHP Docker images,
 When adding additional PHP extensions, you will need an intermediate build stage:
 
 ```dockerfile
+# Dockerfile
 FROM dunglas/frankenphp AS builder
 
 # Add additional PHP extensions here

docs/early-hints.md

@@ -1,6 +1,11 @@
+---
+title: Sending HTTP 103 Early Hints from PHP with FrankenPHP
+description: FrankenPHP natively supports the HTTP 103 Early Hints status code, letting PHP applications preload assets before the final response is ready.
+---
+
 # Early Hints
 
-FrankenPHP natively supports the [103 Early Hints status code](https://developer.chrome.com/blog/early-hints/).
+FrankenPHP natively supports the [103 Early Hints status code](https://developer.mozilla.org/docs/Web/HTTP/Reference/Status/103).
 Using Early Hints can improve the load time of your web pages by 30%.
 
 ```php

docs/embed.md

@@ -1,3 +1,8 @@
+---
+title: Embedding PHP Apps as Standalone Binaries with FrankenPHP
+description: How to package a PHP application (including Symfony or Laravel) as a self-contained static binary with FrankenPHP, the PHP interpreter, PHP extensions and Caddy.
+---
+
 # PHP Apps As Standalone Binaries
 
 FrankenPHP has the ability to embed the source code and assets of PHP applications in a static, self-contained binary.
@@ -6,7 +11,7 @@ Thanks to this feature, PHP applications can be distributed as standalone binari
 
 Learn more about this feature [in the presentation made by Kévin at SymfonyCon 2023](https://dunglas.dev/2023/12/php-and-symfony-apps-as-standalone-binaries/).
 
-For embedding Laravel applications, [read this specific documentation entry](laravel.md#laravel-apps-as-standalone-binaries).
+For embedding Laravel applications, see [the Laravel-specific embedding instructions](laravel.md#laravel-apps-as-standalone-binaries).
 
 ## Preparing Your App
 
@@ -42,7 +47,7 @@ composer install --ignore-platform-reqs --no-dev -a
 composer dump-env prod
 ```
 
-### Customizing the Configuration
+### Customizing the Embedded FrankenPHP Configuration
 
 To customize [the configuration](config.md), you can put a `Caddyfile` as well as a `php.ini` file
 in the main directory of the app to be embedded (`$TMPDIR/my-prepared-app` in the previous example).
@@ -54,6 +59,7 @@ The easiest way to create a Linux binary is to use the Docker-based builder we p
 1. Create a file named `static-build.Dockerfile` in the repository of your app:
 
    ```dockerfile
+   # static-build.Dockerfile
    FROM --platform=linux/amd64 dunglas/frankenphp:static-builder-gnu
    # If you intend to run the binary on musl-libc systems, use static-builder-musl instead
 
@@ -97,7 +103,7 @@ EMBED=/path/to/your/app ./build-static.sh
 
 The resulting binary is the file named `frankenphp-<os>-<arch>` in the `dist/` directory.
 
-## Using The Binary
+## Using the Embedded FrankenPHP Binary
 
 This is it! The `my-app` file (or `dist/frankenphp-<os>-<arch>` on other OSes) contains your self-contained app!
 
@@ -125,18 +131,18 @@ You can also run the PHP CLI scripts embedded in your binary:
 ./my-app php-cli bin/console
 ```
 
-## PHP Extensions
+## PHP Extensions in the Embedded Binary
 
 By default, the script will build extensions required by the `composer.json` file of your project, if any.
 If the `composer.json` file doesn't exist, the default extensions are built, as documented in [the static builds entry](static.md).
 
 To customize the extensions, use the `PHP_EXTENSIONS` environment variable.
 
-## Customizing The Build
+## Customizing the Embedded Binary Build
 
 [Read the static build documentation](static.md) to see how to customize the binary (extensions, PHP version...).
 
-## Distributing The Binary
+## Distributing the Embedded Binary
 
 On Linux, the created binary is compressed using [UPX](https://upx.github.io).