Serve a .md file for every published guide - #242
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
site/src/pages/llms.txt.tstold agents:That was false.
site/src/pages/guides/[slug].md.tsonly emitted a.mdroute for guides present inAGENT_ARTIFACTS: 10 of 36 published guides. Verified live on 2026-08-16:/guides/brief-the-model.md200,/guides/new-claude-lineup.md404,/guides/make-your-agents-proactive.md404.Fix
Make the claim true instead of narrowing it.
/guides/<slug>.mdnow builds for all 36 published guides.Guide bodies are MDX shaped for the page, so
site/src/data/guideMarkdown.tsconverts them:<PullQuote /><Exercise>## Field exerciseand its contents<Chalk><p class="lede"><SkillCopy /><RoutineFlow />,<CompanionLog /><FirmwareCta /><span class="sec-no">01</span><a href>and root-relative linksFenced code blocks pass through untouched.
llms.txtstates the general rule again, and keeps the list (still derived fromagentArtifactFor, so it cannot drift) of the 10 addresses that serve a ready-to-use file instead of the article.Verification
npm run buildinsite/passes, which runs the em-dash, heading-length, and layout copy gates. Checks overdist/: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, andpower-start-sessions-with-enhance-prompt.mdend 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.