Skip to content

Serve a .md file for every published guide - #242

Merged
ryanportfolio merged 2 commits into
mainfrom
claude/llms-txt-md-artifact-claim
Aug 17, 2026
Merged

Serve a .md file for every published guide#242
ryanportfolio merged 2 commits into
mainfrom
claude/llms-txt-md-artifact-claim

Conversation

@ryanportfolio

@ryanportfolio ryanportfolio commented Aug 17, 2026

Copy link
Copy Markdown
Owner

Problem

site/src/pages/llms.txt.ts told agents:

Every guide is also published as a plain-markdown skill file for agents: swap the guide URL's trailing slash for ".md"

That was false. site/src/pages/guides/[slug].md.ts only emitted a .md route for guides present in AGENT_ARTIFACTS: 10 of 36 published guides. Verified live on 2026-08-16: /guides/brief-the-model.md 200, /guides/new-claude-lineup.md 404, /guides/make-your-agents-proactive.md 404.

Fix

Make the claim true instead of narrowing it. /guides/<slug>.md now builds for all 36 published guides.

  • The 10 guides with an agent artifact are unchanged. They still serve the skill or distilled agent file, byte for byte the same text the copy plate on the page offers.
  • The other 26 serve a plain-markdown version of the guide itself: title, description, catalogue line, link back to the page, objectives, prerequisites, the converted body, the FAQ, and the sources.

Guide bodies are MDX shaped for the page, so site/src/data/guideMarkdown.ts converts them:

In the MDX In the .md
<PullQuote /> Blockquote plus creator, work, timestamp, and link
<Exercise> ## Field exercise and its contents
<Chalk> Blockquote
<p class="lede"> Plain paragraph
<SkillCopy /> One line pointing at the copy plate on the page, with the save path
<RoutineFlow />, <CompanionLog /> One line noting a figure sits there
<FirmwareCta /> Dropped, it is a site call to action, not guide content
<span class="sec-no">01</span> Dropped, decorative numbering
<a href> and root-relative links Absolute markdown links

Fenced code blocks pass through untouched.

llms.txt states the general rule again, and keeps the list (still derived from agentArtifactFor, so it cannot drift) of the 10 addresses that serve a ready-to-use file instead of the article.

Verification

npm run build in site/ passes, which runs the em-dash, heading-length, and layout copy gates. Checks over dist/:

md files: 36
guides listed in llms.txt: 36   md routes built: 36
listed guides missing a .md: []      .md with no guide listed: []
files with leftover markup: 0 of 36     (no JSX, HTML tags, braces, or imports outside code fences)
artifact route byte-identical to source file: true   (brief-the-model.md)
generated files with 3+ newlines: none      CR left in output: none
em dash in any generated md: none

Also spot-read the rendered output of new-claude-lineup.md, keep-a-growing-knowledge-base-accurate.md, automate-a-workflow-as-a-claude-routine.md, why-ai-makes-slop-and-how-to-catch-it.md, and power-start-sessions-with-enhance-prompt.md end to end: tables, code fences, links, pull quotes, exercise, FAQ, and sources all read correctly.

Not verified here: the live 404s can only be confirmed gone after deploy.

ryanportfolio and others added 2 commits August 16, 2026 19:56
llms.txt told agents every guide is published as a plain-markdown file at
the guide URL with the trailing slash swapped for .md. Only the 10 guides
listed in AGENT_ARTIFACTS get a /guides/<slug>.md route, so the other 26
published guides 404 for any agent that follows the instruction. Verified
live on 2026-08-16: /guides/brief-the-model.md 200,
/guides/new-claude-lineup.md and /guides/make-your-agents-proactive.md 404.

Replace the claim with an Agent files section built from the same
agentArtifactFor map the .md route uses, so the list cannot drift from the
routes again. Each entry gives the title, the .md URL, whether it is an
installable skill or an agent guide, and the suggested save path.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The llms.txt claim that every guide is published as markdown was false: the
.md route only covered the 10 guides in AGENT_ARTIFACTS, so the other 26
404ed. Rather than narrow the claim, make it true.

/guides/<slug>.md now builds for all 36 published guides. Guides with an
agent artifact keep serving that file byte for byte, the same text the copy
plate offers. The rest serve a plain-markdown version of the guide itself:
title, description, catalogue line, page link, objectives, prerequisites,
the converted body, the FAQ, and the sources.

Guide bodies are MDX shaped for the page, so guideMarkdown.ts converts them.
Pull quotes become blockquotes with attribution, the exercise becomes a
Field exercise heading, chalk asides become blockquotes, decorative section
numbers and the skills call to action drop out, figures and copy plates
leave a one-line pointer to the page, and inline anchors and root-relative
links become absolute markdown links. Fenced code blocks pass through
untouched.

llms.txt states the general rule again and keeps the derived list of the 10
addresses that serve a skill or agent file instead of the article.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@ryanportfolio ryanportfolio changed the title Fix false .md artifact claim in llms.txt Serve a .md file for every published guide Aug 17, 2026
@ryanportfolio
ryanportfolio merged commit a940b99 into main Aug 17, 2026
3 checks passed
@ryanportfolio
ryanportfolio deleted the claude/llms-txt-md-artifact-claim branch August 17, 2026 00:17
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