Conversation
|
@ceIia is attempting to deploy a commit to the Rocicorp Team on Vercel. A member of the Team first needs to authorize it. |
|
Thank you for the contribution @ceIia! Are you aware of https://zero.rocicorp.dev/docs/llms? What does this PR achieve better/differently than that? |
just added a description to the PR, hopefully this explains things! |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
it does! |
Seems like it. I also think the content of the https://zero.rocicorp.dev/docs/llms page should change to describe the features, but I can do that eventually. Or you can in a subsequent PR. Whatever. Thanks a ton for this contribution, I love it! |
| "build": "npm run build:search && npm run build:llms && next build", | ||
| "build:search": "tsx lib/generateSearchIndex.ts", | ||
| "build:llms": "node generate-llms.js", | ||
| "build:llms": "npx --yes tsdown lib/generate-llms.ts --outDir dist --skipLibCheck && node dist/generate-llms.mjs", |
There was a problem hiding this comment.
Perhaps since the .md files are runtime-generated, this root page should be too. It seems like we could use routes-config.ts directly at runtime to generate that root file rather than the build-time thing.
2 participants
what this does
this PR adds two main things:
.mdversions of all doc pages (e.g./docs/introduction.md) via a rewrite to a/raw/[...slug]/route.ts.why i did this
i've been copying links to .md versions of docs from sites that support it (Next.js, Bun, Elysia, Knock, etc.) into Cursor constantly (basically add .md to the docs i need, and dump/paste it directly into Cursor or whatever AI i'm currently chatting with). most of the time, it's a way easier and optimized way to give context to the AI about what i'm working on than trying to explain something myself.
for example, i'm currently refactoring our synced queries implementation and kept needing to reference Zero docs, but there isn't an .md version, so it was either:
how i got here with llms.txt
initially i just implemented the .md support (first commit). then @aboodman commented about the llms.txt file, which made me actually dig into how this is supposed to work.
turns out i'd been misunderstanding llms.txt this whole time. i thought the point was to dump your entire docs into a single massive file, which seemed odd for context windows. but after reading llmstxt.org, i realized the main llms.txt file is (i think?) actually meant to be a compact map/index that helps LLMs navigate to the specific pages they need. the llms-full.txt is the comprehensive version (still not sure exactly when you'd use it vs just following the links in the main file).
looking at how other projects do it:
they all follow this pattern: main file is a curated guide with links + descriptions, full version expands everything.
changes in this PR
commit 1: .md support
[...slug]/route.tsthat serves markdown versions of doc pagespage.mdandpage/index.mdpatternscommit 2: llms.txt improvements
lib/docs-utils.tsto avoid duplicationnotes/questions
should we link to .md versions in llms.txt? right now llms.txt links to the HTML pages. maybe it should link to the .md versions since that's more LLM-friendly? not sure what the convention is here.
this entire llms.txt change might just be a huge skill issue, with me not understanding how to use llms.txt properly. maybe having one giant file is fine and i'm just doing it wrong? if so feel free to close this or cherry-pick just the .md commit.
the
build:llmscommand is now super ugly, i know, i'm sorry. i just couldn't figure out why ts-node/node/tsx hate me and ESM so much, so i just transpile the script on-the-fly instead, and execute it in the same command. is this ok? (oh Bun, how i miss you...)examples of .md in action
.mdappended now works the same way