jekyll-agent-markdown 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aefdb0b717baa8666d581d48746d9b0afad4f730bbf25af6e534dc4a13800ec8
-  data.tar.gz: c702b617f5b8b022f7f3ddc5fe05ca69eeeadc94ed8ecbb87d20b84406c33291
+  metadata.gz: 239761c2150364ff0d2966b3b7999f03a65c578bffeb144f2f69c4ad5da2c6cc
+  data.tar.gz: 9b7d54ce53a9f8cf68c6278a6811bd1405c89d21440a99920f64ac509dfdfc4c
 SHA512:
-  metadata.gz: aef9d1e51132fd68ea7f6e0936addd32c5d69d1da0ef0a9c721df1076d6e9ee99680f7bd2b6c1005af3080b1fd0cf8091da49a68d423acfb8d587afa2ad64007
-  data.tar.gz: db2b8abb8fdb9c4d622483bffc2fadf7c32d65b20b1f338d6c2e09bcdefe6a51c351d32cdd203befdb4a97ec111689833432f794592bb2ac81a78799e56b19c9
+  metadata.gz: e955bf1a3cc544b9b0e4c5b0fe76e0f95d2550ee57f2ccc73d31e0f2f817e460391833ff9a4cd8097e72bcdc94b901afdd017e7343c9613fb51f4b9b19e95328
+  data.tar.gz: ca1cb1d9b76c276a34d83a515ca0f1211014b43c27e05e6aee398884c483354b3825906ef7b527d739ec7a6b909abbbc81d2862d539e9d36fb1bca19194752e3

data/CHANGELOG.md

@@ -1,4 +1,15 @@
-## [Unreleased]
+## [0.4.0] - 2026-08-25
+
+- Export Markdown-backed pages and selected output collections alongside posts.
+- Add per-document export, index, section, optional, and document-header settings.
+- Curate `llms.txt` with sections and descriptions, and add optional `llms-full.txt` output.
+- Register `{% agent_markdown_link %}` and expose `agent_markdown_url` for custom layouts.
+- Package Cloudflare Workers, Netlify Edge, and nginx+njs negotiation recipes.
+- Preserve existing posts-only defaults, collision handling, raw Markdown, and metadata output.
+
+## [0.3.1] - 2026-08-20
+
+- Include the site author in each exported article's metadata footer on the same line as published and updated dates.
 
 ## [0.3.0] - 2026-08-20
 

data/README.md

@@ -1,10 +1,14 @@
 # jekyll-agent-markdown
 
-Export Jekyll posts as raw Markdown next to their normal HTML output, and publish a small `llms.txt` index.
+Export Jekyll content as Markdown siblings and curated `llms.txt` and `llms-full.txt` indexes.
+
+AI agents and LLM crawlers read Markdown better than rendered HTML.
+This plugin publishes a Markdown copy of each exported post, page, and collection document next to its HTML.
+It also writes the index files described by the [llms.txt convention](https://llmstxt.org).
 
 ## Installation
 
-Add the gem to your site's `Gemfile` plugin group:
+Add the gem to your site's `Gemfile`.
 
 ```ruby
 group :jekyll_plugins do
@@ -12,44 +16,68 @@ group :jekyll_plugins do
 end
 ```
 
-Then run `bundle install` and enable it in `_config.yml`:
+Install dependencies.
+
+```sh
+bundle install
+```
+
+The `:jekyll_plugins` group already enables the plugin.
+If you keep the gem outside that group, list it under `plugins:` instead.
 
 ```yaml
 plugins:
   - jekyll-agent-markdown
 ```
 
-## Configuration
+## Quick Start
 
-Both exports are enabled by default:
+Configure the sources you want and build the site.
 
 ```yaml
+url: https://example.com
+collections:
+  guides:
+    output: true
 agent_markdown:
-  posts: true
-  llms_txt: true
-  sort: desc
-  include_author: true
-  include_dates: true
+  pages: true
+  collections:
+    - guides
 ```
 
-`posts`, `llms_txt`, `include_author`, and `include_dates` accept `true`, `false`, or one of the false-style strings `"false"`, `"no"`, and `"off"` (case-insensitively). `sort` accepts `asc` or `desc` and defaults to `desc`, ordering the `llms.txt` article list by normalized published date. Posts with a missing, incomplete, or invalid published date are listed last in their existing order. Unknown keys and other values stop the build with a configuration error instead of being silently ignored. An explicit per-post `agent_markdown` value follows the boolean-setting rules, so a mistyped opt-out cannot publish raw source by accident.
+```sh
+bundle exec jekyll build
+```
 
-By default, `llms.txt` includes the blog author's name from either a scalar Jekyll setting (`author: Jane Doe`) or a mapping (`author: { name: Jane Doe }`). If no author name is configured, the line is omitted. Set `include_author: false` under `agent_markdown` to omit it explicitly.
+The build now writes:
 
-Set `url` to your site's absolute HTTP(S) URL; the `llms.txt` index uses it to generate absolute article links:
+- `/llms.txt`, an index of the exported documents
+- a Markdown sibling for every post, Markdown page, and `guides` document, such as `/guides/start.md` next to `/guides/start/`
 
-```yaml
-url: https://example.com
-```
+## Usage
+
+Enable the sources you want.
 
-When `url` is missing, contains credentials, a query, or a fragment, or is not an absolute HTTP(S) URL, `llms.txt` is skipped with a warning and the rest of the build continues. The build only fails when you set `llms_txt` explicitly in `_config.yml`, since that states clear intent.
+- Posts export by default.
+- Markdown-backed pages need `pages: true`.
+- Markdown collection documents need `collections` and `output: true`.
+- Non-Markdown pages, non-Markdown collection documents, and generated pages are ignored.
+- A missing or non-output collection fails the build.
+- A selected collection with a Markdown document lacking a public document URL fails.
+- The reserved `posts` collection cannot appear in `collections`.
 
-Set `agent_markdown: false` to disable both exports, or `agent_markdown: true` to enable both explicitly (same as leaving it unset). The strings `"false"`, `"no"`, and `"off"` are also treated as false, case-insensitively.
+Use site-level `agent_markdown: true` to enable the defaults.
+Use site-level `agent_markdown: false` to disable every export.
+Boolean settings accept `true` and `false` scalars.
+They also accept `"false"`, `"no"`, and `"off"` as false.
+False-style strings are case-insensitive and work in front matter.
+Unknown keys, wrong types, and invalid combinations fail the build.
+Duplicate collection names also fail the build.
 
-Markdown sibling paths are deterministic:
+Markdown siblings follow the permalink.
 
 | Post URL | Markdown URL |
-|---|---|
+| --- | --- |
 | `/foo/` | `/foo.md` |
 | `/foo.html`, `/foo.htm` | `/foo.md` |
 | `/foo.html/` | `/foo.html.md` |
@@ -57,34 +85,71 @@ Markdown sibling paths are deterministic:
 | `/foo` | `/foo.md` |
 | `/` | `/index.md` |
 
-Extensions are matched case-insensitively, and percent-encoded aliases are compared by their final decoded destination. Destination ownership also treats case-only and Unicode-normalization aliases as equivalent on every platform, keeping builds portable across filesystems. File-versus-directory conflicts are reserved as well. Before adding an export, the plugin checks every page, static file, and writable collection document already known to Jekyll. The existing destination owner wins; later post exports are skipped with a warning and omitted from `llms.txt`. A committed `llms.txt` wins in the same way.
-
-The generated file preserves the post's original Markdown body as its initial content, with no front matter, HTML conversion, or Liquid rendering. Liquid tags and directives such as `{{ site.title }}` are published literally. By default, the plugin appends the post's published `date` and optional `last_modified_at` value as a small footer:
+Each post export ends with a metadata footer built from the available dates and the site author.
+Disable it with `include_dates: false` and `include_author: false`.
 
 ```text
+Post body.
+
 ---
-Published at: 2026-01-01 | Updated at: 2026-02-03
+Published at: 2026-01-01 | Updated at: 2026-01-05 | Author: Example Author
 ```
 
-Each available date is formatted as `YYYY-MM-DD`. String values must contain an explicit year, month, and day; missing, incomplete, and invalid values and their labels are omitted. An empty post contains only the metadata line, without a leading `---` that could be mistaken for front matter. Set `include_dates: false` to omit date metadata from both Markdown exports and `llms.txt`, leaving the body-only export shape used before date metadata was introduced.
-
-Exclude one post with front matter:
+Set per-document settings in front matter.
 
 ```yaml
 agent_markdown: false
 ```
 
-Expose the alternate representation from a layout:
+```yaml
+agent_markdown:
+  export: true
+  index: true
+  section: Documentation
+  optional: false
+  include_document_header: true
+```
 
-```liquid
-{% if page.agent_markdown_url %}
-  <link rel="alternate" type="text/markdown" href="{{ page.agent_markdown_url | relative_url }}">
-{% endif %}
+Use `optional: true` without `section` for the `Optional` section.
+Front matter cannot enable a globally excluded source kind.
+`export: false` also disables `index`.
+Do not combine `export: false` with `index: true`.
+Do not combine `optional: true` with `section`.
+
+Add `include_document_header: true` to prepend a small header.
+That setting needs a valid absolute `url`.
+A valid `url` uses HTTP(S) without credentials, a query, or a fragment.
+
+The header holds the title, the front matter description when present, and a `Source:` link to the HTML page.
+The body below the divider stays untouched.
+
+```markdown
+# About this site
+
+A one-line description from front matter
+
+Source: https://example.com/about/
+
+---
+
+## What we do
+
+Raw page body.
 ```
 
-The conditional omits the link for opted-out and colliding posts. The `relative_url` filter adds `baseurl` for sites deployed below the domain root.
+Use `llms_txt: true` for the compact index.
+`llms.txt` has two layouts.
+With the posts-only defaults it keeps the original single-list layout, byte-for-byte identical with releases before 0.4.0.
+Enabling pages, collections, or descriptions, or using `section` or `optional` in front matter, switches to the sectioned layout shown below.
 
-The generated `/llms.txt` is a compact index, for example:
+Add `include_descriptions: true` for sanitized descriptions.
+Descriptions fall back to the document excerpt.
+Use `sort: asc` or `sort: desc` for each section.
+Set `include_author: false` or `include_dates: false` to trim metadata.
+Mark a document `optional: true` to move it under `Optional`.
+Default sections appear before custom sections.
+Custom sections keep their first-occurrence order.
+The `Optional` section always appears last.
 
 ```text
 # Example Site
@@ -95,24 +160,148 @@ Author: Example Author
 
 ## Articles
 
-> Posts only. Pages and collections are not included.
-
 - [First article](https://example.com/articles/first.md) | Published at: 2026-01-01
+
+## Pages
+
+- [About](https://example.com/about.md): About page
+
+## Guides
+
+- [Getting started](https://example.com/guides/start.md)
+
+## Optional
+
+- [Reference](https://example.com/reference.md)
 ```
 
-## Deployment notes
+Use `llms_full_txt: true` for the full index.
+It uses the same document selection as `llms.txt`.
+It still works when `llms_txt: false`.
+Each entry expands into a full Markdown document block.
+Set `url` to a valid absolute HTTP(S) URL first.
+The generator warns once when the rendered file exceeds 1 MiB.
+
+```text
+# Example Site
+
+## Articles
 
-Configure your host to serve generated `.md` files as `Content-Type: text/markdown; charset=utf-8` and, when appropriate, `X-Robots-Tag: noindex`. This gem writes files only; it cannot set HTTP response headers. Generated files refuse to write through symlinks inside the destination. GitHub Pages safe mode may not run arbitrary plugins, so use a separate build/deploy pipeline there.
+### [First article](https://example.com/articles/first.md)
 
-## v0.1.0 limitations
+Source: https://example.com/articles/first/
 
-Only posts are exported. Pages and custom collections, custom Markdown transformations or templates, front-matter allowlisting, automatic response headers, sitemaps, and richer article metadata are intentionally deferred.
+Body of the first article.
+```
+
+Add the alternate link from a layout.
+
+```liquid
+{% agent_markdown_link %}
+```
+
+It renders a discovery link for the current page.
+
+```html
+<link rel="alternate" type="text/markdown" href="/about.md">
+```
+
+The tag is baseurl-aware.
+It is empty for opted-out or collided documents.
+Use `page.agent_markdown_url` when custom markup needs the generated path.
+
+On collision, existing destinations win.
+Generated claims run through posts, then pages, then configured collections.
+Later exports skip with a warning and receive no `agent_markdown_url`.
+They are also omitted from both indexes.
+A committed `llms.txt` or `llms-full.txt` also wins on collision.
+Collision detection only sees files Jekyll knows about when this plugin runs at `priority :low`.
+Another plugin generating files at `priority :lowest` runs later and can still claim the same destination.
+
+## Options
+
+Boolean settings accept `true`, `false`, and false-style strings.
+Unknown keys and invalid values raise `Jekyll::Errors::FatalException`.
+
+These are the complete defaults.
+
+```yaml
+agent_markdown:
+  posts: true
+  pages: false
+  collections: []
+  llms_txt: true
+  llms_full_txt: false
+  include_descriptions: false
+  include_document_header: false
+  include_author: true
+  include_dates: true
+  sort: desc
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `posts` | `true` | Export posts. |
+| `pages` | `false` | Export pages. |
+| `collections` | `[]` | Export output collections named here. |
+| `llms_txt` | `true` | Write `llms.txt`. |
+| `llms_full_txt` | `false` | Write `llms-full.txt`. |
+| `include_descriptions` | `false` | Append sanitized descriptions to `llms.txt`. |
+| `include_document_header` | `false` | Prepend document headers to Markdown exports. |
+| `include_author` | `true` | Include author metadata. |
+| `include_dates` | `true` | Include published and updated dates. |
+| `sort` | `desc` | Order each section by normalized publish date. |
+
+The default `llms_txt` warns and skips when `url` is missing or invalid.
+Explicitly configuring `llms_txt` makes an invalid `url` fatal.
+`llms_full_txt` needs a valid absolute `url` whenever enabled.
+Document headers enforce the same URL rules only when enabled.
+
+## Deployment
+
+The plugin writes static files; any host can serve them as-is.
+Content negotiation is optional and happens at the host, not in Ruby.
+A negotiating host serves the Markdown sibling when a request prefers `text/markdown`.
+It falls back to HTML when the sibling does not exist.
+
+[examples/](examples/) ships dependency-free recipes that share one negotiation contract:
+
+- [Cloudflare Workers](examples/cloudflare)
+- [Netlify Edge Functions](examples/netlify)
+- [nginx with njs](examples/nginx)
+
+All three negotiate only `GET` and `HEAD` requests and skip static assets.
+See the [deployment guide](docs/deployment.md) for the full negotiation contract and host setup.
+
+## Compatibility
+
+Ruby 3.2 or newer is required.
+Jekyll 4.3 or newer is required, but Jekyll 5 is unsupported.
+The plugin writes files only.
+There is no automatic injection into rendered HTML.
+Layouts must invoke `{% agent_markdown_link %}` explicitly.
+It does not handle content negotiation.
+It does not generate crawler policy, analytics, middleware, response headers, or crawler permissions.
+It publishes raw Markdown without rendering Liquid.
+Post exports append enabled date and author metadata.
+Document headers prepend content only when enabled.
+Destination ownership is normalized across case, Unicode normalization, encoded aliases, and file-versus-directory conflicts.
+
+### Limitations
+
+Page and collection exports require authored Markdown and public URLs.
+Generated pages and non-Markdown page or collection sources are ignored.
+Raw Liquid may expose source directives to Markdown readers.
+GitHub Pages safe mode may require an external build pipeline.
 
 ## Development
 
-Run `bundle exec rake` after `bundle install` to execute both Minitest and RuboCop.
+Run the tests and RuboCop.
 
-The entry point explicitly loads the plugin's small implementation tree without an additional runtime loader dependency. Implementation files also declare their own prerequisites so public constants can be required directly in isolation.
+```sh
+bundle install
+bundle exec rake
+```
 
 ## License
 

data/docs/deployment.md

@@ -0,0 +1,138 @@
+# Deploy HTML and Markdown variants
+
+`jekyll-agent-markdown` writes files; the web host decides how those files are represented over HTTP. This guide defines one negotiation contract and provides dependency-free starting points for Cloudflare Workers, Netlify Edge Functions, and nginx with njs.
+
+The packaged examples assume Jekyll's pretty permalinks: an HTML URL such as `/articles/example/` is backed by `_site/articles/example/index.html`, while this plugin writes `_site/articles/example.md`. They also map `/` to `/index.md`, remove `.html` or `.htm` before adding `.md`, and map an extensionless `/example` to `/example.md`. Adapt the path helpers if the site uses a different permalink scheme. Build the site first and point each example's `_site` setting at that output.
+
+## Negotiation contract
+
+Apply negotiation to page URLs, not to CSS, JavaScript, images, fonts, or other static assets.
+
+| Request | Result |
+| --- | --- |
+| Missing `Accept` or wildcard-only `Accept: */*` | HTML |
+| A more specific media range | Its `q` value overrides a less-specific wildcard for that representation |
+| Different effective HTML and Markdown quality | The supported representation with the larger quality wins |
+| At equal quality | Markdown wins only when the request explicitly names `text/markdown`; otherwise HTML wins |
+| A representation with effective `q=0` | Excluded, even if a less-specific wildcard has a positive quality |
+| Neither `text/html` nor `text/markdown` acceptable | `406 Not Acceptable` |
+| A negotiated Markdown variant that does not exist | HTML when HTML is acceptable; otherwise the Markdown `404` |
+| A URL ending in `.md` | Markdown regardless of `Accept`; this URL is not negotiated |
+| A method other than `GET` or `HEAD` | Not negotiated |
+
+The examples calculate an effective quality independently for `text/html` and `text/markdown`. Media-range specificity is applied before explicit `q` values are compared: an exact type is more specific than `text/*`, which is more specific than `*/*`. Supported representation parameters, currently `charset=utf-8`, add specificity. Invalid quality values make that range unacceptable instead of silently broadening access.
+
+This follows HTTP's [`Accept` precedence and quality rules](https://www.rfc-editor.org/rfc/rfc9110.html#section-12.5.1). Returning 406 is an intentional server policy when none of the available representations is acceptable; HTTP also permits a server to disregard the preference, but these examples do not. See [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.7).
+
+### Representation availability
+
+Negotiation selects among representations that actually exist. This plugin exports posts by default, so on a site that has not enabled `pages` or `collections` most page URLs have no `.md` sibling. A request preferring Markdown for such a URL must not become a 404 when the host could have served HTML.
+
+Each example therefore fetches the selected variant and, when a negotiated Markdown variant returns 404 and HTML is acceptable, retries the HTML variant and labels the response as HTML. Two cases deliberately do not fall back: an explicit `.md` URL, because that URL names one representation rather than negotiating, and a request that excluded HTML with `q=0`, because no acceptable representation exists.
+
+### Request methods
+
+Negotiation applies to `GET` and `HEAD`. The nginx example rejects other methods with `405 Method Not Allowed` and an `Allow` header, because an njs subrequest is always a `GET` and would otherwise turn a `POST` into a static read of the page body. The Cloudflare and Netlify examples hand non-page and non-matching requests to the platform's own asset handler, which applies its method rules.
+
+## Response contract
+
+Every successful variant has an explicit UTF-8 content type:
+
+```http
+Content-Type: text/html; charset=utf-8
+```
+
+or:
+
+```http
+Content-Type: text/markdown; charset=utf-8
+```
+
+Every response selected from `Accept`, including a 406 response, carries:
+
+```http
+Vary: Accept
+```
+
+`Vary` prevents a shared cache from reusing an HTML response for a Markdown request or the reverse. Preserve existing `Vary` fields when adding `Accept`; see the HTTP [`Vary` definition](https://www.rfc-editor.org/rfc/rfc9110.html#section-12.5.5).
+
+HTML and Markdown advertise each other with a [`Link` response header](https://www.rfc-editor.org/rfc/rfc8288.html). For example:
+
+```http
+Link: </articles/example.md>; rel="alternate"; type="text/markdown"
+```
+
+and the Markdown response advertises HTML:
+
+```http
+Link: </articles/example/>; rel="alternate"; type="text/html"
+```
+
+The explicit `.md` URL always returns `text/markdown; charset=utf-8`, even if a caller sends `Accept: text/html`. The `text/markdown` media type is registered by [RFC 7763](https://www.rfc-editor.org/rfc/rfc7763.html).
+
+## Cloudflare Workers
+
+Copy [`examples/cloudflare`](../examples/cloudflare) into the deployment project, or adapt its paths. `wrangler.toml` binds the Jekyll output as `ASSETS` and sets `run_worker_first = true`; without that setting, a matching static asset can bypass negotiation. The Worker passes non-page assets straight through and uses `env.ASSETS.fetch()` for selected variants.
+
+The relevant primary documentation is Cloudflare's [static assets binding and `run_worker_first` reference](https://developers.cloudflare.com/workers/static-assets/binding/). Set `compatibility_date` to the deployment project's chosen current date and confirm the `_site` path before deploying.
+
+## Netlify Edge Functions
+
+Copy [`examples/netlify/netlify.toml`](../examples/netlify/netlify.toml) and [`markdown-negotiation.ts`](../examples/netlify/netlify/edge-functions/markdown-negotiation.ts) to the corresponding locations in the site repository. The catch-all declaration is minimal and easy to test; narrow the declared paths or add exclusions on a large site to avoid invoking the function for assets that it only passes through.
+
+The Edge Function calls `context.next()` for the requested HTML or explicit Markdown asset. When a page URL negotiates Markdown, it fetches the `.md` sibling; that same-site request runs the Edge Function again but terminates on the explicit `.md` branch. Review Netlify's [Edge Functions API](https://docs.netlify.com/build/edge-functions/api/) and [declaration and request-chain rules](https://docs.netlify.com/build/edge-functions/declarations/) before combining this example with other rewrites or Edge Functions.
+
+## nginx with njs
+
+Install nginx's JavaScript module, place [`negotiation.js`](../examples/nginx/negotiation.js) at `/etc/nginx/njs/negotiation.js`, adapt the `_site` filesystem path in [`nginx.conf`](../examples/nginx/nginx.conf), then validate and reload nginx. Current njs recommends the QuickJS engine; the example selects it with `js_engine qjs`. The example also sets `include mime.types` and a binary `default_type`, without which its pass-through location would serve CSS, JavaScript, fonts, and images as `text/plain`.
+
+The public location delegates page requests to `js_content`. The handler performs an internal subrequest to a private static location, sets the variant headers, and returns the buffer. `subrequest_output_buffer_size` must exceed the largest generated page, so change the example's `10m` ceiling to fit the site's real output and memory budget. Consult the official [`ngx_http_js_module` directives](https://nginx.org/en/docs/http/ngx_http_js_module.html) and [njs request/subrequest API](https://nginx.org/en/docs/njs/reference.html).
+
+## Pre-release verification
+
+Replace the sample origin and article paths, deploy to a staging hostname, and run this curl matrix. Use GET with discarded bodies so the check exercises the same response path as production clients.
+
+```sh
+origin=https://staging.example.com
+article=/articles/example/
+markdown=/articles/example.md
+page=/about/
+
+curl -sS -D - -o /dev/null -H 'Accept:' "$origin$article"
+curl -sS -D - -o /dev/null -H 'Accept: */*' "$origin$article"
+curl -sS -D - -o /dev/null -H 'Accept: text/markdown' "$origin$article"
+curl -sS -D - -o /dev/null -H 'Accept: text/html, text/markdown' "$origin$article"
+curl -sS -D - -o /dev/null -H 'Accept: text/*;q=0.8, text/html;q=0.4' "$origin$article"
+curl -sS -D - -o /dev/null -H 'Accept: text/markdown;q=0, */*;q=0.8' "$origin$article"
+curl -sS -D - -o /dev/null -H 'Accept: application/json' "$origin$article"
+curl -sS -D - -o /dev/null -H 'Accept: text/markdown;q="1"' "$origin$article"
+curl -sS -D - -o /dev/null -H 'Accept: text/html' "$origin$markdown"
+curl -sS -D - -o /dev/null -H 'Accept: text/markdown' "$origin$page"
+curl -sS -D - -o /dev/null -H 'Accept: text/markdown, text/html;q=0' "$origin$page"
+```
+
+Expected results, in order:
+
+| Case | Status | Content-Type |
+| --- | --- | --- |
+| Missing `Accept` | 200 | `text/html; charset=utf-8` |
+| Wildcard-only | 200 | `text/html; charset=utf-8` |
+| Explicit Markdown | 200 | `text/markdown; charset=utf-8` |
+| Equal explicit HTML and Markdown | 200 | `text/markdown; charset=utf-8` |
+| More-specific HTML is lower quality than `text/*` Markdown | 200 | `text/markdown; charset=utf-8` |
+| Exact Markdown exclusion overrides wildcard | 200 | `text/html; charset=utf-8` |
+| Neither supported | 406 | `text/plain; charset=utf-8` |
+| Invalid quoted quality | 406 | `text/plain; charset=utf-8` |
+| Explicit `.md` despite HTML preference | 200 | `text/markdown; charset=utf-8` |
+| Page with no Markdown sibling | 200 | `text/html; charset=utf-8` |
+| Same page with HTML excluded | 404 | the host's own error representation |
+
+For every negotiated 200 response, also verify `Vary: Accept` and the appropriate alternate `Link`. Check the explicit Markdown URL's HTML `Link`. Finally, submit representative public staging URLs to the [acceptmarkdown.com public scanner](https://acceptmarkdown.com/public) and retain its results with the release evidence. The scanner is a useful external pre-release check, not a substitute for the matrix or host logs.
+
+## Crawler policy is separate
+
+`Content-Signal` is an evolving crawler-policy convention, not a transport requirement for HTML/Markdown negotiation. Whether a site permits search, AI input, or model training is a decision for the site owner, informed by the site's content rights and legal advice. The examples deliberately do not generate crawler permissions. Review the current [Content Signals project](https://contentsignals.org/) and the behavior of the crawlers that matter to the site, then write and audit an owner-approved policy; do not copy a generated crawler policy without that review.
+
+## Runtime gaps to validate
+
+These packaged examples statically lock the shared HTTP behavior, but they are not deployed by this gem. Before production, validate host-specific routing, redirects, custom error pages, caching, compression, conditional requests, range requests, base paths, non-pretty permalinks, large response bodies, and interaction with any existing middleware. Confirm that a missing Markdown sibling produces the site's intended error rather than mislabeled content, and monitor 406 rates after launch for clients with unexpected `Accept` headers.