Skip to content

Publish per-page Markdown twins at {route}.md instead of {route}/index.md#56

Merged
phil-scott-78 merged 1 commit into
mainfrom
llms-flat-markdown-twins
Jun 24, 2026
Merged

Publish per-page Markdown twins at {route}.md instead of {route}/index.md#56
phil-scott-78 merged 1 commit into
mainfrom
llms-flat-markdown-twins

Conversation

@phil-scott-78

Copy link
Copy Markdown
Contributor

What

Per-page LLM Markdown twins now land at {route}.md (Claude-docs style) instead of {route}/index.md.

The page /getting-started/first-page now publishes its Markdown copy at /getting-started/first-page.md — a sibling of the first-page/ page folder — rather than nesting it inside as /getting-started/first-page/index.md. This conforms to how Claude's docs and the broader llms.txt ecosystem name their Markdown copies.

The root home stays at /index.md (since /.md isn't a usable URL, and the index.llms.md machine-home already keys on /index.md).

Why

{route}/index.md forced the agent-facing copy into a nested folder. {route}.md is the convention agents (and Claude Code's Accept: text/markdown WebFetch) expect, and it keeps the twin next to the page in the output tree.

Changes

Core

  • LlmsTxtService.BuildCoLocatedMarkdownPath emits {key}.md (root index.md). This is the single source the public-URL builder, internal-link rewriter, and HTML <link rel="alternate"> hints all derive from.
  • LlmsArtifactContentService collapses the ExactClaim("/index.md") + SuffixClaim("/index.md") pair into one SuffixClaim(".md") — covers root and every nested twin. Content routes are extensionless so it shadows none, and the resolver stays authoritative (returns null → router falls through) for any .md it didn't generate.

Serving / chrome

  • DocSite Pages.razor + App.razor body cue, BlogSite Blog.razor alternate hints.
  • docs/cloudflare/_worker.jsmarkdownTwin() now maps /x/x.md, /x/ and /x/index.html/x.md, and //index.md for production Accept: text/markdown negotiation.

Tests & docs

  • Updated LlmsTxtAndSearchEndpointTests assertions, plus the docs/examples that describe the convention (index.llms.md, the markdown-for-agents tutorial, the llms-txt how-to, two example sites).

Verification

  • dotnet build clean.
  • LlmsTxtAndSearchEndpointTests (17) + projection/smoke tests (13) pass.
  • A real dotnet run -- build emits 521 {route}.md twins and exactly one index.md (the root). Confirmed tutorials/getting-started/first-page.md coexists with first-page/, the llms-only migrating-via-ai.md has no HTML folder, and sidecar_url points at .md while canonical_url keeps the page's trailing-slash URL.

Note for reviewers

docs/Pennington.Docs/Content/blog/llms-txt.md is intentionally not in this PR — its index.md.md correction is entangled with separate in-flight blog-revamp edits in the working tree, and will ride along with that work.

…}/index.md

Co-located Markdown copies now land at the page URL with `.md` appended
(Claude-docs style) — e.g. /getting-started/first-page.md — instead of nesting
them as /getting-started/first-page/index.md. The root home keeps /index.md,
since /.md is not a usable URL.

- LlmsTxtService.BuildCoLocatedMarkdownPath emits {key}.md; the public-URL
  builder, internal-link rewriter, and HTML alternate hints all derive from it.
- LlmsArtifactContentService collapses the ExactClaim("/index.md") +
  SuffixClaim("/index.md") pair into one SuffixClaim(".md"): it covers the root
  and every nested twin, content routes are extensionless so it shadows none,
  and the resolver stays authoritative (null -> falls through) for any .md it
  did not generate.
- Updated the DocSite/BlogSite <link rel="alternate"> hints, the Cloudflare
  Markdown content-negotiation worker, integration tests, and the docs/examples
  that describe the convention.
@github-actions

Copy link
Copy Markdown

🛰️ Docs preview: https://pr-56.pennington-dev.pages.dev

Rebuilt on every push to this PR; torn down when it closes.

@phil-scott-78 phil-scott-78 merged commit 7f89d13 into main Jun 24, 2026
4 checks passed
@phil-scott-78 phil-scott-78 deleted the llms-flat-markdown-twins branch June 24, 2026 16:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant