docs: add SEO frontmatter, llms.txt, and code-block hygiene#2394
docs: add SEO frontmatter, llms.txt, and code-block hygiene#2394
Conversation
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.
There was a problem hiding this comment.
Pull request overview
This PR improves documentation discoverability and ingestion by adding consistent SEO/LLM YAML frontmatter to English docs, tightening code-block language/filename hygiene, standardizing overly-generic headings, and introducing an llms.txt index that points agents/crawlers at canonical English pages.
Changes:
- Add YAML frontmatter (
title,description) across Englishdocs/*.md. - Rename generic headings to more specific, topic-oriented ones and adjust related wording.
- Improve code blocks (language tags like
caddyfile/bash, and add first-line “filename/purpose” comments) and add a rootllms.txtdoc index.
Reviewed changes
Copilot reviewed 26 out of 26 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| llms.txt | Adds an AI/crawler-facing index of canonical English docs. |
| docs/x-sendfile.md | Adds frontmatter and renames a generic configuration heading to a more specific one. |
| docs/worker.md | Adds frontmatter, makes headings more specific, and changes CLI blocks to bash. |
| docs/wordpress.md | Adds frontmatter, renames headings, and adds “Caddyfile/filename” comments to code blocks. |
| docs/symfony.md | Adds frontmatter, renames headings, and adds “Caddyfile/filename” comments to code blocks. |
| docs/static.md | Adds frontmatter and renames headings/anchors for clearer navigation. |
| docs/production.md | Adds frontmatter, clarifies link text, and adds “Caddyfile/filename” comments to code blocks. |
| docs/performance.md | Adds frontmatter, refines section headings, and improves code block annotations. |
| docs/observability.md | Adds frontmatter for SEO/ingestion. |
| docs/migrate.md | Adds frontmatter and adds “filename” comments to config examples while refining link text. |
| docs/metrics.md | Adds frontmatter for SEO/ingestion. |
| docs/mercure.md | Adds frontmatter for SEO/ingestion. |
| docs/logging.md | Adds frontmatter for SEO/ingestion. |
| docs/laravel.md | Adds frontmatter, renames headings, and adds “Caddyfile/filename” comments to code blocks. |
| docs/known-issues.md | Adds frontmatter and adds a filename comment to a script example. |
| docs/internals.md | Adds frontmatter and refines headings; adds an inline comment to a C snippet for clarity. |
| docs/hot-reload.md | Adds frontmatter, renames headings, and corrects the Caddyfile code fence language. |
| docs/github-actions.md | Adds frontmatter for SEO/ingestion. |
| docs/extensions.md | Adds frontmatter and adds “filename/purpose” comments to many code blocks. |
| docs/extension-workers.md | Adds frontmatter, renames headings, and adds purpose comments to examples. |
| docs/embed.md | Adds frontmatter and makes headings/link text more specific. |
| docs/early-hints.md | Adds frontmatter and updates the 103 Early Hints reference link. |
| docs/docker.md | Adds frontmatter, renames headings, and adds “Dockerfile” comments to code blocks. |
| docs/config.md | Adds frontmatter, refines headings, and adds “Caddyfile/Dockerfile” comments to code blocks. |
| docs/compile.md | Adds frontmatter and adjusts a platform subheading. |
| docs/classic.md | Adds frontmatter for SEO/ingestion. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- markdownlint: tell MD025 to ignore the YAML frontmatter title so the in-body H1 stops being flagged as a duplicate top-level heading. - gitleaks: refresh the JWT example fingerprint in .gitleaksignore to match the new line number after frontmatter was added to mercure.md. - symfony.md: update the inbound link to x-sendfile.md to point at the new section anchor. - extension-workers.md: fix a pre-existing "a any other goroutine" typo flagged by Copilot.
Per review feedback, a bare `# Caddyfile` or `# Dockerfile` on the first line of a `caddyfile` or `dockerfile` fenced block restates information the language tag already carries and just adds noise. Remove those generic headers and keep only the comments that name a specific file (e.g. `# compose.yaml`, `# static-build.Dockerfile`, `// public/index.php`) or describe the block's purpose.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 28 out of 28 changed files in this pull request and generated 2 comments.
Comments suppressed due to low confidence (1)
docs/config.md:319
- Renaming this section changes the anchor (previously
#php-config). There is at least one existing reference that still points toconfig.md#php-config(e.g. docs/migrate.md:18), which will become a broken link unless updated or a compatibility anchor is added.
# or
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Restore the original `## Environment Variables`, `## PHP config`, and `## Hardening Images` headings. Those were already specific in context, and renaming them broke inbound anchor links from README.md and from migrate.md, performance.md. - Update the worker.md cross-link to symfony.md to point at the new `## Symfony Worker Mode with FrankenPHP` anchor. - Restore the original developer.chrome.com link for the 103 Early Hints reference. The MDN URL swap was an unrequested side-edit.
henderkes
left a comment
henderkes
left a comment
There was a problem hiding this comment.
Stopping the review here because the same point comes up again and again:
I strongly believe that we should optimise the visible documentation for humans, not LLMs. I'm fine with adding invisible extra notes for LLMs, but users shouldn't constantly feel like they get context repeated for no reason
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 28 out of 28 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| @@ -1,2 +1 @@ | |||
| /github/workspace/docs/mercure.md:jwt:88 | |||
| /github/workspace/docs/mercure.md:jwt:90 | |||
| /github/workspace/docs/mercure.md:jwt:95 | |||
- compile.md: adopt henderkes' frontmatter wording. Use the actual artifact name (libphp.so) and "shared library" instead of the vaguer "PHP as a Library" / "dynamic library". - embed.md: revert two agent-introduced edits that henderkes flagged. Restore the original Laravel link wording and the `### Customizing the Configuration` heading. The previous attempt read awkwardly and implied FrankenPHP itself was being embedded rather than the user's application.
The binary produced by the embed feature contains FrankenPHP plus the user's PHP application; FrankenPHP itself is not what is being embedded. Drop the misleading "FrankenPHP" qualifier from `## Using the Embedded Binary` so it is consistent with the surrounding headings (`## PHP Extensions in the Embedded Binary`, `## Customizing the Embedded Binary Build`, `## Distributing the Embedded Binary`).
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 28 out of 28 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Per review, the original heading names already read fine in context: the page title and frontmatter establish the FrankenPHP / extension worker / embedded-app framing, so prefixing every section heading with those qualifiers is redundant. For embed.md, "the Embedded Binary" was also misleading: the binary is the artifact that embeds the user's app, not something that is itself embedded. Restore the main wording for: - ## Using The Binary - ## PHP Extensions - ## Customizing The Build - ## Distributing The Binary - ## Registering the Worker - ### Static Registration - ## Interacting with Workers - ## Worker Script - ## Lifecycle Hooks - ### Example
henderkes
left a comment
henderkes
left a comment
There was a problem hiding this comment.
we're using a, the and other short words in lowercase elsewhere
I'm generally not convinced that we should be capitalizing words that shouldn't be capitalized, but that's for a different discussion
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 28 out of 28 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Apply henderkes' suggestion to use lowercase short words ("the") in the
three embed.md headings he flagged, and fix the sibling
`## Using the Binary` heading the same way so all three remain
consistent within the file.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 28 out of 28 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Use Chicago-style title case: capitalize first/last word and all major words; lowercase articles (a, an, the), coordinating conjunctions (and, but, or, nor, for, so, yet), and prepositions regardless of length (with, from, after, between, across, etc.). Also fix the "Mode :" / "Emulation :" stray spaces before colons in extension-workers.md, capitalize "User" in the parenthetical, and title-case "Real-Time", "PHP Config", and the lowercase "packages"/ "binary" / "Component" / "using" cases that slipped in.
- config.md: "all the file" → "all the files"; drop stray "using" in "enable HTTPS using for all the hostnames"; remove a duplicated "start a new shell" line. - docker.md: "by the one contained your custom modules" → "with the one containing your custom modules"; add missing article in "run as a non-root user". - extensions.md: "deeper dive to type juggling" → "into type juggling"; "Forces to design" → "Forces you to design". - known-issues.md: "fully binary" → "fully static binary". - laravel.md: "explicitly the pass `--log-level` option" → "explicitly pass the `--log-level` option"; "you can use enable Mercure" → "you can enable Mercure". - mercure.md: "must used to sign" → "must be used to sign"; "tokens generated aerodynamically using with a trusted" → "generated dynamically using a trusted"; "library handled" → "library handles". - metrics.md: add missing articles in "absolute path of worker file". - static.md: add missing article before "`scratch` Docker image". - worker.md: "number of request" → "number of requests". - x-sendfile.md: replace mid-sentence period with comma so the preamble before the examples reads as one sentence.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 28 out of 28 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
`worker.md#symfony-runtime` never matched a heading on main either: worker.md has a `## Worker Mode for Symfony` section, not a Symfony Runtime section. Point the link at the correct anchor. Verified with a repository-wide audit that resolves every `*.md#anchor` reference in docs/, README.md, CONTRIBUTING.md and SECURITY.md against the actual headings (GitHub-style slugs). After this change, all in-repo anchor links resolve.
|
@henderkes I uniformized title case, there is not really a standard for that but it's common practice: https://en.wikipedia.org/wiki/Title_case |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 28 out of 28 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Yes, I don't mind it, it just gets copilot confused on what's a minor word and what isn't. We've had it forever, I just want to keep it consistent. |
|
I'll switch to "sentence case" so it's easier for everyone, including Copilot |
…ding - Headings (H1-H4) and frontmatter titles now use sentence case across every English doc and llms.txt: capitalize the first word and proper nouns (FrankenPHP, Symfony, Docker, Caddy, etc.); lowercase common words. Anchors are unchanged because GitHub slugifies case-insensitively. - compile.md: "load PHP as a dynamic library" -> "shared library" (the artifact is libphp.so / libphp.dylib, which is a shared object). Wording about *PHP extensions* still uses "dynamic" since that's the term PHP itself uses for runtime-loaded extensions. - symfony.md: rename `## Running Symfony with the Symfony Docker Image` to `## Running Symfony with Symfony Docker`. Symfony Docker is a template project (Dockerfile, GHA setup, Compose files), not a Docker image.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 28 out of 28 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Summary
title,description) to every English doc underdocs/*.mdfor SEO and LLM/RAG ingestion.## Setup,## Configuration, etc.) to topic-specific ones; updates the one inbound cross-link affected by an anchor rename.console→bash,caddy→caddyfile), and a first-line filename or purpose comment added on blocks that represent a real file.llms.txtindex 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).Notes
docs/<lang>/are intentionally untouched. Re-rundocs/translate.phpafter merge to propagate the new frontmatter and renamed headings.