The docs build had a fragile implicit dependency on www's filesystem
(`../../../apps/www/public/llms`), flagged by the docs team in #44670.
Rather than formalising that dependency with a shared package, this PR
eliminates it entirely by making www the sole owner of llms content
assembly.
**How it works now:**
`/llms/[slug]` handles all `/llms/*.txt` requests via a 3-step cascade:
1. Dynamic content — `pricing.txt` generated at request time from
`shared-data` imports
2. Local file — product overviews read from `data/llms/`
3. Docs proxy — reference docs (guides, js, dart, etc.) fetched from the
docs app
No hardcoded slug lists, so adding new content just works.
**What changed:**
- `apps/docs/scripts/llms.ts` trimmed to only generate per-source
reference files — www now owns `llms.txt`, `llms-full.txt`, and product
overviews
- Removed `generateLlmsPricing.mjs` build script — pricing generated
dynamically from `shared-data`
- Removed llms rewrites from `rewrites.js` — routes handle everything
with consistent `Cache-Control: public, s-maxage=3600,
stale-while-revalidate=86400`
- Product overview `.txt` files moved from `public/llms/` → `data/llms/`
so all requests go through routes for consistent caching
**Docs team concerns from GROWTH-773:**
| Concern | Resolution |
|---------|-----------|
| Docs build depends on www files at a fragile relative path | Path
removed — docs no longer reads from www |
| www restructuring breaks docs with no obvious connection | Eliminated
— no cross-app filesystem dependency |
| No build order enforcement between www and docs | Not needed — docs
doesn't depend on www's build output |
## To test
- `curl <preview>/llms.txt` — markdown index with doc + product overview
links
- `curl <preview>/llms-full.txt` — combined product overviews + docs
content
- `curl <preview>/llms/pricing.txt` — dynamically generated pricing
tables
- `curl <preview>/llms/auth.txt` — product overview from local file
- `curl <preview>/llms/guides.txt` — proxied from docs app
- `curl <preview>/llms/nonexistent.txt` — 404
- Verify `Cache-Control` header on all responses
---------
Co-authored-by: Alaister Young <10985857+alaister@users.noreply.github.com>
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## What kind of change does this PR introduce?
feature
## What is the current behavior?
Currently, old GitHub discussions appear in the docs search instead of
troubleshooting guides in docs/guides/troubleshooting
## What is the new behavior?
Local troubleshooting guides appear in the search
## Additional context
<img width="958" height="846" alt="CleanShot 2026-01-31 at 23 37 33@2x"
src="https://github.com/user-attachments/assets/445fab5d-764a-4b4d-b4ef-c29ab675a9ae"
/>
**troubleshooting.ts** - New source loader that reads local MDX files
from content/troubleshooting/ directly instead of fetching from GitHub
Discussions API
- Generates correct docs paths: /guides/troubleshooting/{slug}
- Uses type = 'troubleshooting' for proper search result mapping
- Sets slug: undefined to avoid trailing # in URLs
- Checksum includes title/topics/keywords so metadata-only changes
trigger re-indexing
- Left comments for review
**index.ts** - Replaced GitHub discussion sources with local
troubleshooting sources
- Removed GitHubDiscussionLoader, fetchDiscussions,
buildGithubUrlToSlugMap imports
- Added fetchTroubleshootingSources and TroubleshootingSource
- Updated SearchSource type union
**globalSearchModel.ts** - Changed type mapping from
'github-discussions' to 'troubleshooting'
**generate-embeddings.ts** - Removed GitHub App env vars from required
list (DOCS_GITHUB_APP_ID, DOCS_GITHUB_APP_INSTALLATION_ID,
DOCS_GITHUB_APP_PRIVATE_KEY) since they're no longer needed
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Local troubleshooting articles are now indexed and appear directly in
search results for easier access to step‑by‑step guidance.
* Search UI now recognizes a Troubleshooting page type and shows
appropriate icons/sections.
* **Refactor**
* Search sourcing switched from external discussion feeds to local
troubleshooting sources to improve relevance and indexing consistency.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Illia Basalaiev <illiab@IMB3.local>
Co-authored-by: Charis Lam <26616127+charislam@users.noreply.github.com>
Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
* Remove extra file.
* Remove unneeded tsconfig.jsons.
* Add @/* alias for importing in-package files to all apps.
* Remove baseUrl from all apps except studio (it'll require changes in almost all files).
* Fix baseUrl issues in docs, ui-library and design-system.
* Fix the typecheck for cms app. Fix all baseUrl errors in the cms app.
* Add deprecated flag to baseUrl in www.
* feat: alternate search index for nimbus
Create an alternate search index for Nimbus that filters out
feature-flagged pages (equivalent to setting all feature flags to
false).
Notes:
- Creates two new DB tables, `page_nimbus` and `page_section_nimbus`,
which are filtered versions of `page` and `page_section`
- Makes `nimbus` versions of all the DB search functions
- Refactored the embedding upload script. Changes to make it faster (got
annoyed by how slow it was when testing...), incorporate retries, and
produce better summary logs.
- Upload script, when run with the environment variable
ENABLED_FEATURES_OVERRIDE_DISABLE_ALL, produces and uploads the
alternate search index
- Changed all the search calls in frontend/API to check for
`isFeatureEnabled('search:fullIndex')` to determine whether to search
the full or alternate index
* ci: produce nimbus search indexes on merge
* fix: turn full search index on
Pages that are disabled in navigation/site rendering are still shown in
llms.txt. This change filters those pages out of the llms.txt build as
well.
Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
* refactor: reading markdown docs files
Refactor how Markdown docs files are read:
- Reuses the same logic across search index generation & page generation
- Improves the indexed content for search:
- Stops removing MDX components, which often contain useful
information like Admonitions
- Denormalizes Partials and CodeSamples for more complete content
This is a prerequisite step for implementing the "Copy docs as Markdown"
functionality.
Only touches regular guides for now, not federated ones.
* fix: tailwind build error (#37728)
We changed to default to ESM imports a while ago, which means local
builds are now breaking because the Tailwind uses a require. Changed to
CJS for Tailwind config file. (I have no idea how this has been working
on Vercel all this time.)
* style: prettier
Implement hybrid search for the /docs/api/graphql searchDocs endpoint. Prepend a more descriptive title and introduction to database advisor docs so they rank more highly when directly searched for.
* docs: add cursor rule for embedding generation process
Add documentation for cursor IDE about how docs embeddings are generated,
including the workflow for creating and uploading semantic search content.
* feat: improve API reference metadata upload with descriptive content
- Add preembeddings script to run codegen before embedding generation
- Enhance OpenApiReferenceSource to generate more descriptive content including
parameters, responses, path information, and better structured documentation
* feat: add Management API references to searchDocs GraphQL query
- Add ManagementApiReference GraphQL type and model for API endpoint search results
- Integrate Management API references into global search results
- Update test snapshots and add comprehensive test coverage for Management API search
* style: format
Adds support for indexing database lint warnings from the Splinter repository
into the docs search. Creates a new LintWarningsGuideLoader that fetches
markdown files from the Splinter repo and processes them as individual
searchable entries in the database advisors guide.
* ci(docs): fix sync process
GraphQL codegen needs to be run before sync because otherwise the types
are missing. Missed this in local testing because codegen had already
been run for other reasons.
* fix(troubleshooting sync): unresolved import
* ci(docs lint): fix commenting workflow
strictNullChecks was off for docs, which lets errors slip through and
leads to incorrect required/optional typing on Zod-inferred types. This
PR enables strictNullChecks and fixes all the existing violations.
Our environment variables are a bit of a mess, so cleaning them up:
- We have duplicate environment variables that resolve to the same thing
but just have different names, deduplicating all of these
- We have a .env.development (for publicly safe variables) and a
.env.example, we
really only need one
- Privately, we have a .env (for running scripts) and a .env.local (for
Next.js). Changing the dotenv source for scripts, so again we only need
one
Scripts currently use CJS, which is causing a bit of a mess when trying
to use shared utilities from the app. Converting everything to ESM so
there are fewer conflicts when adding new scripts going forward.
* feat(content api): add client library api reference search results
Allow searchDocs results to also return function references from the
client library APIs
* fix(content api): refine language enum handling
* feat: llms.txt
* feat: split llms.txt into multiple files
We have too many docs, so the concatenated text file uses an unreasonable amount of tokens. Chunk it up a little so it's more usable.
Small DX improvement for writing troubleshooting guides. When a new troubleshooting guide is created, it is auto-populated with the tempalte (as long as docs dev is running).
Search index pipeline shouldn't be trying to read troubleshooting section yet (those are still searched via GH discussions). Trying to read it errors as they don't have the same frontmatter shape as other guides content.
The end of the Great Migration is here!!!
Moves the last pages over, deleting pages like the FAQ that we don't use
and that contain duplicated information anyway.
Dev secret auth page URL had to change as App Router doesn't like the
leading underscores in the path.
Also fixes the not-found recommendations to use the proper Next.js
not-found page so it will return a 404 as it should. (I was under the
erroneous impression that I couldn't get the pathname in not-found.tsx,
that is not true, so this works better.)
* Bump the version of turbo to 2.0.3.
* Fix the breaking changes in turbo config.
* Make the npm version more loose.
* Fix the build command for the database-design app.
* Try adding some env vars to the turbo for www.
* Add more missing env vars.
* Bump the turbo version to 2.0.4.
* Remove SUPABASE_SERVICE_ROLE_KEY from docs#build since it's used by other scripts, not by build.
- Remove the cleanup function. (Too much potential for concurrently
running workflows to stomp all over each other. This should run in a
separately scheduled task that locks the table for cleanup.)
- Exit with error code if updates error so problem will show up in
Action notifications.
Keeps track of fine-grained (per section) edit times for docs content.
Once daily, a GitHub Action runs that:
- Checks whether content hashes have changed for each section
- Updates the table that tracks content edit times if the hashes have changed
Note: The cron job isn't scheduled yet. I'll run the Action manually a few times to validate it, then turn it on in another PR.
* fix: correct mgmt api naming
* feat: new command to generate mgmt api sections
* feat: sort section items
* chore: tidy up
* fix: add generate sections to the default command
* feat: add gha to auto update mgmt api docs
* chore: tidy up
* fix: operationId logic to support self-hosting references
* chore: update latest mgmt api specs
* chore: update latest mgmt api specs
Begin the process of moving our MDX files into their own content directory.
Fixed a few minor bugs re: ToC and tabs not rerendering consistently on page navigation. (The ToC thing wasn't a problem before the refactor, the tabs thing is a problem on prod.)
Moved MDX files can't import their own components, so everything they require needs to be back in the component prop for mdx-remote's serializer. Cleaned this up a bit and lazy-loaded heavy/rare stuff. Also, the component prop doesn't take arbitrary objects (only actual components), so imported data has to be wrapped in a component.
Alaister Young