mirror of
https://github.com/supabase/supabase.git
synced 2026-10-06 09:55:06 +03:00
cli/ref-doc
5
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Pamela Chia
|
21a27eeb4f |
feat(www): canonicalize homepage markdown at /index.md (#49384)
The www root markdown lived at an accidental URL: `/.md` served the
homepage markdown only because middleware strips the `.md` suffix and
the empty slug fell through to the homepage allowlist entry, while the
canonical-looking `/index.md` 404'd. The served markdown also opened
with stale legacy positioning copy that no longer matches the site. I
renamed the homepage content slug to `index` end-to-end so `/index.md`
is the one canonical markdown URL.
**Changed:**
- **`/index.md` serves the homepage markdown (200 `text/markdown`)**:
`content/md/homepage.md` renamed to `index.md`; the middleware bare-root
slug mapping, the generator's sort special-case, and the homepage
alternate tag follow, so the tag now advertises `/index.md`.
- **Legacy aliases 308 to the canonical URL**: `/.md`, `/homepage.md`,
and bare `/index` redirect via `lib/redirects.js`; `/llms/homepage.txt`
retargeted straight to `/index.md` to avoid a redirect chain. New
`next.config.test.ts` assertions pin all four.
- **Positioning refreshed**: the markdown now opens with "Supabase is
the Postgres development platform" (matching the site title), replacing
the outdated tagline.
- **Generator safety**: the redirect-exclusion filter in
`generateMdContent.mjs` now exempts the `index` slug (its HTML page is
`/`, not `/index`, so a `/index` redirect never refers to it), and the
build fails if `content/md/index.md` ever goes missing while middleware
still maps `/` to the `index` slug.
- **CI actually runs the new assertions**: I widened the `www-tests.yml`
paths filter to include `apps/www/lib/**/*.js`,
`apps/www/content/md/**`, and `apps/www/scripts/**/*.mjs`. It previously
only matched `.ts*` and the next.config files, so a PR touching only
`lib/redirects.js`, the markdown content, or the generator would skip
the tests that pin these redirects.
**Note:** the existing homepage alternate tag still exists, re-pointed
to the canonical URL. Whether the homepage should advertise a markdown
sibling at all is a separate decision; leaving it aimed at a 308 would
break tag consumers. Positioning wording is editorial, happy to tweak.
## To test
Tested on Vercel preview:
- [x] `curl -si <preview>/index.md`: expect 200 `content-type:
text/markdown`, body opens with the Postgres development platform
positioning and no longer contains the old tagline
- [x] `curl -sI <preview>/.md`: expect 308 with `location: /index.md`
- [x] `curl -sI <preview>/homepage.md` and `curl -sI
<preview>/llms/homepage.txt`: expect 308 with `location: /index.md`
- [x] `curl -sI <preview>/index`: expect 308 with `location: /`
- [x] `curl -s -H "Accept: text/markdown" -o /dev/null -w "%{http_code}
%{content_type}" <preview>/`: expect `200 text/markdown` (bare-URL
negotiation unchanged)
- [x] `curl -s <preview>/ | grep -o 'type="text/markdown"
href="[^"]*"'`: expect href ending `/index.md`
## Linear
- fixes GROWTH-1117
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **New Features**
- Added support for `/index.md` as the canonical Markdown representation
of the homepage.
- Added permanent redirects for legacy homepage Markdown and text URLs.
- Added `/index` to `/` redirect handling.
- **Bug Fixes**
- Updated homepage metadata, alternate links, Markdown negotiation, and
content generation to consistently use the new canonical path.
- Improved homepage content description.
- **Tests**
- Expanded coverage for homepage Markdown routes, redirects, and URL
matching.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
|
||
|
Pamela Chia
|
f208743432 |
fix(www): changelog md negotiation slug-set gate (#49357)
Bare-URL `Accept: text/markdown` negotiation never fires on changelog entries authored after the GitHub-discussions backfill: the middleware gate `/^changelog\/\d+/` only matches legacy numeric slugs (from `legacy_gh_discussion` frontmatter), so agents that signal markdown via Accept get HTML on every new entry. I found this in the independent review round on #48475; pre-existing, not introduced there. **Changed:** - **Non-legacy entries negotiate markdown**: `generateMdContent.mjs` now lists `public/changelog/*.md` (written moments earlier by `generateStaticContent.mjs` in the same `content:build:core` chain) and emits a `CHANGELOG_PAGES` set into the generated module; the middleware regex becomes a set lookup, so negotiation coverage derives from the exact static files served and can't drift from what's published. - **Unknown and deep changelog paths stop negotiating**: the old regex prefix-matched paths like `changelog/100/bar` and nonexistent numeric slugs, rewriting them to missing `.md` files (404 under a markdown Accept); they now pass through to the dynamic route's canonicalizing 308/404. - **Build guard**: zero collected changelog slugs on Vercel fails the build (today a zero-entry changelog fetch ships empty output with a green build), and a shape assertion fails the build if collected slugs ever lose the `changelog/` prefix the middleware matches on. Locally without `CHANGELOG_SYNC_APP_*` secrets it warns and changelog negotiation is off, matching the absent content. - **`/changelog` index gated the same way**: the index slug is emitted into the set only when `public/changelog.md` was generated, replacing the hardcoded `slug === 'changelog'` branch; locally without secrets the index no longer rewrites to a nonexistent file. **Note:** script order in `content:build:core` is load-bearing (static content generation must precede md content generation); the Vercel guard turns a reorder into a loud build failure instead of a silent empty gate. ## To test Tested on the Vercel preview (`zone-www-dot-com` deployment of head `f451da3`): - [x] `curl -sI -H "Accept: text/markdown" <preview>/changelog` and `curl -sI <preview>/changelog.md`: got 200 `text/markdown` (index via the generated gate) - [x] `curl -sI -H "Accept: text/markdown" <preview>/changelog/pipelines`: got 200 `text/markdown` (prod today returns `text/html`) - [x] Same curl against the legacy numeric slug `48235-migration-of-...`: got 200 `text/markdown` (no regression) - [x] `curl -sI -H "Accept: application/json" <preview>/changelog/pipelines`: got 406 (prod today returns 200 HTML) - [x] Explicit `.md` fetches for both slug shapes (`/changelog/pipelines.md`, `/changelog/48235-....md`): got 200 `text/markdown` - [x] `curl -sI -H "Accept: text/markdown" <preview>/changelog/does-not-exist-xyz`: got a 404 HTML passthrough from the dynamic route, not a 406 - [x] `pnpm test middleware.test.ts` in `apps/www` at head: 41/41 pass (36 pre-existing + 5 new). No CI job runs the www vitest suite, so this local run is the only oracle for the new tests. ## Linear - fixes GROWTH-1062 <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **New Features** - Improved changelog page handling, including markdown versions of published entries. - Added content negotiation for supported changelog formats, with clear responses for unsupported requests. - **Bug Fixes** - Prevented unpublished numeric-prefix pages from being treated as published. - Fixed deep links under published changelog entries. - **Reliability** - Changelog availability is now detected automatically, with improved validation during content generation. <!-- end of auto-generated comment: release notes by coderabbit.ai --> |
||
|
Pamela Chia
|
9ae6e54dd5 |
fix(www): exclude redirected slugs from generated markdown (#48476)
11 of the generated `MD_PAGES` entries are blog slugs whose HTML pages 308-redirect away via `apps/www/lib/redirects.js` before any `<head>` renders. They can never carry an alternate tag and Accept negotiation never fires (Next.js `redirects()` runs before middleware), so their `.md` siblings are orphaned content reachable only by guessing the suffixed URL. Six of them duplicate live, correctly-tagged pages (`/customers/*`, `/pricing`). **Changed:** - `generateMdContent.mjs` derives an exclusion set from `lib/redirects.js` at generation time: any unconditional exact-match redirect source (wildcard/param patterns and conditional `has`/`missing` redirects are skipped) drops the matching slug from both `MD_CONTENT` and `MD_PAGES`. The build log names every excluded slug, currently the 11 known ones. - Self-maintaining by design (per the decision recorded on the issue): a future redirected post auto-excludes on the next build, and removing a redirect brings its `.md` sibling back. The MDX sources stay in the repo; nothing is deleted. - Effect on the 11 slugs: alternate tags stay absent (nothing rendered them anyway), and explicit `.md` URLs go from serving orphaned markdown to 404, the same external effect deletion would have had. ## To test Tested locally: - [x] `node scripts/generateMdContent.mjs` logs `🚫 Excluded 11 redirected slugs: ...` naming exactly the 11 known slugs; output drops 483 → 472 pages - [x] Generated file carries no MD_CONTENT/MD_PAGES key for any excluded slug (raw URL mentions inside other posts' bodies remain, as expected) - [x] `apps/www` vitest: 71/71 (GROWTH-1013 drift tests unaffected) Post-merge: - [ ] `https://supabase.com/blog/case-study-xendit.md` returns 404 (previously 200 orphaned markdown); `https://supabase.com/pricing.md` still 200 ## Linear - fixes GROWTH-1022 <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Bug Fixes** * Excluded content with valid exact-path redirects from generated documentation. * Preserved content associated with conditional or wildcard redirects. * Updated generated page counts and output statistics to reflect the filtered content. <!-- end of auto-generated comment: release notes by coderabbit.ai --> |
||
|
Pamela Chia
|
baabcb189c | feat(www): serve blog, customers, events as .md for AI agents (#45403) | ||
|
Pamela Chia
|
d409836ca7 |
feat(www,docs): serve marketing pages as .md, advertise via link rel=alternate (#45277)
## Summary Adds `/<page>.md` routes for 10 marketing/product pages (homepage, auth, database, edge-functions, realtime, storage, vector, pricing, modules/cron, modules/queues) so AI agents can fetch clean markdown instead of parsing JS-rendered HTML. Also advertises the markdown alternate via `<link rel="alternate" type="text/markdown">` on marketing and docs pages so agents can discover it. Pricing is generated dynamically via `generatePricingContent()` (single source of truth with `/llms.txt` and `/llms-full.txt`); the other nine slugs are bundled at build time from `content/md/*.md` into a `MD_CONTENT` map. Supersedes #44891 (rebased fresh off current master to avoid a 9-commit replay over rename/rename conflicts created by #44897). ## Changes - New `/api-v2/md/[...slug]` route handler returns the bundled markdown (or dynamic pricing) with `Content-Type: text/markdown`, `X-Content-Type-Options: nosniff`, and appropriate cache headers - Middleware rewrites `/<slug>.md` and `Accept: text/markdown` to the API route for the `MD_PAGES` allowlist; trailing-slash variants (`/auth/`) are normalized so they resolve the same as `/auth` - Build-time codegen `scripts/generateMdContent.mjs` scans `content/md/` and emits `app/api-v2/md/content.generated.ts` exporting both `MD_CONTENT` (Map) and `MD_PAGES` (Set, incl. dynamic `pricing`). Fails the build on slug collision between `content/md/` and `DYNAMIC_SLUGS`. Adding a new marketing `.md` is just dropping a file in `content/md/` (also update `PRODUCT_OVERVIEW_LINKS` in `/llms.txt` since that list is editorial). - 8 permanent redirects `/llms/<product>.txt` → `/<product>.md` so legacy URLs in caches and downstream `llms.txt` copies keep working - `/llms.txt` product overview now references `.md` URLs (incl. `modules/cron`, `modules/queues`); `/llms-full.txt` iterates `MD_CONTENT.values()` (homepage first, then alphabetical) and appends dynamic pricing - `/llms/[slug]` route slimmed to proxy SDK reference files (`js.txt`, `dart.txt`, etc.) since redirects handle product slugs and pricing; pricing branch retained as fallback in case redirects are bypassed - `apps/www/pages/_app.tsx` injects the alternate link conditionally based on `MD_PAGES`; `/pricing` (app router) sets it via page metadata - `apps/docs/app/page.tsx` (the `/docs` root) sets the text/markdown alternate to `/llms-full.txt`; per-guide pages override with their specific `.md` URL via `genGuideMeta` in `GuidesMdx.utils.tsx`. Other docs pages (reference, troubleshooting) inherit nothing. - `apps/www/.vercelignore`: replaces the prior `*.md`/`README.md` rules with `*.md` + `!content/md/**/*.md` so Edge Function READMEs and future scratch `.md` files aren't silently shipped to the build artifact - Drops `apps/www/data/llms/*.txt` and the related `outputFileTracingIncludes` - Test coverage for the new middleware branches: `.md` suffix rewrite (allowlisted vs. fall-through), `Accept: text/markdown` content negotiation, trailing-slash normalization ## Testing (Vercel preview) Local dev server smoke tests passing on `:3771` after each iteration. Re-verified on the preview URL after the latest hardening commit: - [x] `curl -I https://<preview>/llms/auth.txt` — expect `308 Permanent Redirect` to `/auth.md` - [x] `curl https://<preview>/auth.md | head -3` — expect `# Supabase Auth` - [x] `curl https://<preview>/pricing.md | head -3` — expect `# Supabase Pricing` with current tier values - [x] `curl https://<preview>/modules/cron.md | head -3` — expect `# Supabase Cron` - [x] `curl -H 'Accept: text/markdown' https://<preview>/ | head -3` — expect `# Supabase` (homepage.md) - [x] `curl https://<preview>/llms.txt` — Product Overview section lists `.md` URLs and includes Cron + Queues - [x] `curl https://<preview>/llms-full.txt | grep -E '^# Supabase (Cron\|Queues\|Pricing)'` — Cron and Pricing each match once; Queues matches twice (marketing module + existing docs guide) - [x] View source on `/`, `/pricing`, `/database` — expect `<link rel="alternate" type="text/markdown" href="/<slug>.md">` - [x] View source on `/docs` — expect `<link rel="alternate" type="text/markdown" href="/llms-full.txt">` - [x] View source on a docs guide page (e.g., `/docs/guides/auth`) — expect per-guide `.md` alternate; reference/troubleshooting pages should NOT emit a markdown alternate - [x] `curl -I https://<preview>/auth.md` — expect `X-Content-Type-Options: nosniff` - [x] `curl -I -L -H 'Accept: text/markdown' https://<preview>/auth/` — should resolve to markdown content (trailing-slash normalization, with Vercel's auto-redirect) ## Linear - fixes GROWTH-760 ## Follow-up (separate PR) GROWTH-760 also asks about extending `.md` to blog/customers/events. Different mechanism (path-prefix middleware, MDX read at request time via `gray-matter`) so it deserves its own review. Will open a follow-up PR after this lands. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Serve prebuilt and dynamic Markdown docs via new markdown endpoints and routing; pages now advertise markdown alternates (including pricing). * Added Cron and Queues module documentation pages. * **Documentation** * Minor formatting tweaks to Realtime and Storage docs. * **Chores** * Added build-time Markdown content generation and adjusted ignore/deploy rules for generated files. * Added redirects from legacy text-based product URLs to new markdown pages. * **Tests** * Expanded tests for markdown routing and content-negotiation behavior. <!-- end of auto-generated comment: release notes by coderabbit.ai --> |