mirror of
https://github.com/supabase/supabase.git
synced 2026-09-06 18:11:51 +08:00
create-pull-request/patch
4 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
Illia Basalaiev
|
ee1eb5dbca |
docs: standardize quickstart guides (#48950)
## 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? Docs update ## What is the new behavior? - All 19 guides follow one step order: create project → set up database → create app → AI tooling → add keys → create client → query data → run it → go to production. Added _template.mdx with structure requirements; it is not enforced with a lint check for now - this will be a separate PR before adding new guides. - 4 new partials replace copy-pasted blocks (AI tooling, connection strings, mobile env vars, going to production). - Error handling: return a message instead of a blank page when a query fails. - All guides verified and tested separately - all work as described. What was fixed: wrong env var names in the Hono sample, a Next.js page that redirected to login, missing database permissions in Refine and Hono, and stale file paths and APIs in SvelteKit, Refine, and TanStack. - Astro, Expo, Python, Laravel, and Rails were live but missing from the quickstart grid or listing page. Added, with two new icons. ## Quick links for review Base preview: https://docs-git-docs-standardize-framework-quickstarts-supabase.vercel.app/docs **Quickstart discovery**: new Astro/Expo/Python/Laravel/Rails entries and icons - [Docs homepage grid](https://docs-git-docs-standardize-framework-quickstarts-supabase.vercel.app/docs) <img width="1998" height="882" alt="CleanShot 2026-08-12 at 12 06 31@2x" src="https://github.com/user-attachments/assets/942eb7e2-1e85-4b20-a6a7-c2b127d31b2b" /> - [Getting started overview](https://docs-git-docs-standardize-framework-quickstarts-supabase.vercel.app/docs/guides/getting-started) <img width="856" height="878" alt="CleanShot 2026-08-12 at 12 13 30@2x" src="https://github.com/user-attachments/assets/d48091a9-7daf-4796-a521-14116b7479c9" /> ### New shared files: **[apps/docs/content/guides/getting-started/quickstarts/_template.mdx]( |
||
|
Danny White
|
c0f1ef51fb |
feat(docs): migrate resources and getting-started to ContentListings (#48517)
## What kind of change does this PR introduce? Docs update / follow-up to #48379. ## What is the current behavior? `/guides/resources` and `/guides/getting-started` hand-roll `GlassPanel` grids in MDX. They look like ContentListings cards after the chrome PR, but they do not use the shared data files, so they miss PostHog `docs_content_listing_clicked` telemetry and the CONTRIBUTING contribution path. ## What is the new behavior? Those pages use `<ContentListings id="…" />` backed by `resources.data.ts` and `getting-started.data.ts`, same pattern as storage. - Section-level `$Show` wrappers stay for framework / web / mobile blocks - Nimbus stays a `$Partial` behind `$Show` - New optional per-item `feature` field gates SDK links (e.g. Flutter / Swift / Kotlin) without splitting whole sections - CONTRIBUTING notes when to use `feature` vs a partial-level `$Show` ## To test Compare the following against `master`: - [Resources](https://docs-git-dnywh-docs-content-listings-resources-239158-supabase.vercel.app/docs/guides/resources): overview, migrate, and postgres grids; icons in light/dark - [Getting started](https://docs-git-dnywh-docs-content-listings-resources-239158-supabase.vercel.app/docs/guides/getting-started): overview, use cases, framework quickstarts, web demos, mobile tutorials; nimbus partial when enabled - Click a card and confirm `docs_content_listing_clicked` fires with the expected `listingId` Everything should look and feel the same. It’s just that we’re using `ContentListings` instead of `GlassPanel` grids. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **New Features** - Added centralized Getting Started and Resources content listings, including quickstarts, demos, tutorials, migration guides, and Postgres resources. - Added feature-based visibility controls for individual content listing items. - **Improvements** - Disabled content is now automatically hidden from documentation pages and generated Markdown. - Pages and sections with no available content are omitted entirely. - External documentation links are more secure. - Updated contribution guidance with instructions and examples for feature flags. <!-- end of auto-generated comment: release notes by coderabbit.ai --> |
||
|
Nik Richers
|
963182f58e |
fix: add hasLightIcon field to ContentListings; revert getting-started-overview to GlassPanel (#47467)
## 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? Bug fix + partial revert. ## What is the current behavior? 1. `ContentListings.client.tsx` unconditionally derives `hasLightIcon` from `Boolean(item.icon)`. `GlassPanel` appends `-light.svg` to the icon path in light mode whenever `hasLightIcon` is true. Framework icons (react, nuxt, hono, redwood, flutter, swift, kotlin, svelte, solidjs, vue, refine, angular, ionic) have no `-light.svg` variants, causing broken image requests in light mode for any ContentListings card that uses them. 2. `getting-started.mdx` uses `<ContentListings id="getting-started-overview" />` (added in #47097) for the top three-card grid (Build with AI tools, API Keys, Local Development). ## What is the new behavior? 1. `hasLightIcon` is now an optional field in the item schema (defaults to `Boolean(item.icon)` for backward compatibility). The component reads `item.hasLightIcon ?? Boolean(item.icon)`, so data files can opt specific icons out of the light-mode variant. 2. `<ContentListings id="getting-started-overview" />` is removed and the original hand-authored GlassPanel grid is restored. The `gettingStartedGetStarted` data entry and its registry import are also removed. ContentListings has no mandate to cover every section of every page: the goal was for hub and overview pages to have a reasonable, standardized link section that tooling can lint for. This page doesn't fit that pattern. ## Additional context | Check | Result | |-------|--------| | `pnpm vitest run lib/content-listings.test.ts` | ✅ 12/12 passed | | `pnpm lint:mdx` (getting-started.mdx) | ✅ No warnings | <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Updated the Getting Started guide with dedicated tiles for Build with AI Tools, API Keys, and Local Development. * Expanded the available Getting Started content listings. * **Bug Fixes** * Improved icon styling in content listings so light icon treatment reflects each item’s configuration. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Nik Richers <nik@validmind.ai> |
||
|
Nik Richers
|
635b2d6050 |
docs: standardise next steps on overview pages with content listings (#47097)
## I have read the CONTRIBUTING.md file. YES ## What kind of change does this PR introduce? This PR helps standardise link sections which is useful for overview pages that frequently use similar sections such as "Next steps", "Get started", or "Examples". Six high-traffic overview pages are migrated as a pilot, with a skill in the new [supabase/docs-agent-skills](https://github.com/supabase/docs-agent-skills) repo to audit and convert the rest in a follow-on PR. Refactored from an initial YAML front matter approach per review feedback from @jeremenichelli. Now implemented as a React component and using existing linting & Markdown export functionality. A second round of review feedback further simplified the architecture: the per-listing component registry was removed in favor of a single `<ContentListings id="..." />` component backed by an ID-keyed data lookup, the listing data moved out of `apps/docs/components/` into `apps/docs/data/content-listings/`, the listing-specific link wrapper was replaced with the existing `<Link>` + `<GlassPanel>` pattern from the rest of the docs, and the headings now defer to the shared `<Heading>` from `MdxBase.shared.tsx` (no parallel marker-to-tag mapping, no typography overrides). Great feedback, thank you! 🙏 Relates to DOCS-1032. ## What is the current behavior? Authors implement these sections however they wish. As a result, overview and index pages use inconsistent patterns for orientation links: some use hand-rolled Markdown lists, some use custom panel/grid components, some use buttons, and some have no guidance about where to go next at all. There is no shared component for these sections and no analytics on those clicks. ## What is the new behavior? Authors add orientation sections in two steps: 1. Define listing data in a `.data.ts` file under `apps/docs/data/content-listings/` (for example, `storage.data.ts`). Each `ContentListingGroup` has a globally-unique `id` like `storage-get-started`. 2. Place a single `<ContentListings id="..." />` component inline in guide MDX. The ID is also the telemetry `listingId`, so the same value disambiguates the section in PostHog dashboards. Grid and list layouts, optional icons (such as `/docs/img/icons/github-icon` with `-light.svg` variants for dark mode), and external URLs are supported. Conditionals that use `$Show` around inline components are also supported, for example for auth pricing. ### Usage example from "Storage" overview page `apps/docs/data/content-listings/storage.data.ts`: ```ts export const storageGetStarted: ContentListingGroup = { id: 'storage-get-started', heading: 'Get started', description: 'Choose the bucket type that fits your use case:', type: 'grid', items: [ { title: 'Files buckets', href: '/guides/storage/quickstart', description: 'Store and serve images, videos, documents, and general-purpose files with direct URL access and row-level security.', }, { title: 'Analytics buckets', href: '/guides/storage/analytics/introduction', description: 'Store data in Apache Iceberg tables for data lakes, logs, and ETL. Query from Postgres via foreign tables with partitioning.', }, { title: 'Vector buckets', href: '/guides/storage/vector/introduction', description: 'Store embeddings and run similarity search for semantic matching, AI, and RAG. Use HNSW indexing, distance metrics, and metadata filtering.', }, ], } ``` `apps/docs/content/guides/storage.mdx`: ```mdx <ContentListings id="storage-get-started" /> ``` Renders as: <img width="689" alt="Storage Get started listing — Files, Analytics, and Vector buckets" src="https://github.com/user-attachments/assets/0d1b9531-962f-40ae-891e-b1e93ff1c939" /> <br>Exported in Markdown as: ```md ## Get started Choose the bucket type that fits your use case: - **[Files buckets](/docs/guides/storage/quickstart):** Store and serve images, videos, documents, and general-purpose files with direct URL access and row-level security. - **[Analytics buckets](/docs/guides/storage/analytics/introduction):** Store data in Apache Iceberg tables for data lakes, logs, and ETL. Query from Postgres via foreign tables with partitioning. - **[Vector buckets](/docs/guides/storage/vector/introduction):** Store embeddings and run similarity search for semantic matching, AI, and RAG. Use HNSW indexing, distance metrics, and metadata filtering. ``` Click tracking fires via PostHog (`docs_content_listing_clicked`): ```json { "action": "docs_content_listing_clicked", "custom_properties": { "targetPath": "/guides/storage/quickstart", "linkTitle": "Files buckets", "groupTitle": "Get started", "listingId": "storage-get-started" } } ``` Still finding my way around PostHog, but I verified on preview deploy that clicking a content listing on `/docs/guides/auth` sends `docs_content_listing_clicked` to `https://api.supabase.green/platform/telemetry/event` and receives HTTP 201. ### Authoring experience Three ways to add or convert content listings: copy the agent prompt first, use snippets for manual edits, or invoke the audit skill for batch follow-on work. Refer to `CONTRIBUTING.md` for the full authoring guide. #### 1. Agent prompt Copy into Cursor or another AI assistant: ```text Add a content listing block for [TOPIC] / [SECTION] (for example, Storage / Examples). Follow CONTRIBUTING § Content listings in apps/docs. - Add data to apps/docs/data/content-listings/[topic].data.ts - Use a globally-unique kebab-case id like `[topic]-[section]` - Place inline in the guide MDX with <ContentListings id="..." /> - Copy structure from storageGetStarted in apps/docs/data/content-listings/storage.data.ts - Run pnpm test:local lib/content-listings.test.ts from apps/docs ``` #### 2. VS Code / Cursor snippets Type these prefixes in the docs workspace (`.vscode/content-listing.code-snippets`): | Prefix | Inserts | | ----------- | -------------------------------------------------------- | | `cl-data` | `ContentListingGroup` export skeleton with namespaced id | | `cl-inline` | `<ContentListings id="…" />` in guide MDX | <img width="658" height="274" alt="image" src="https://github.com/user-attachments/assets/5ef20954-7aee-4925-887d-79a5ae766b37" /> #### 3. Batch audit skill For follow-on overview page conversion or maintenance, use the [`audit-content-listings`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/audit-content-listings/SKILL.md) skill in `docs-agent-skills` (skill, `conversion-manifest.json`, and validation script). Example: ```text Use audit-content-listings. Audit getting-started.mdx, update conversion-manifest.json, then convert the next unconverted section only. ``` ## Additional context The implementation includes a presentational `<ContentListings />` component (grid/list layouts, GlassPanel, telemetry) backed by ID-keyed data modules, and a single markdown export handler that reads the same `id` prop from the JSX and looks up data via the shared registry. Key files: - **Data:** `apps/docs/data/content-listings/` (one `.data.ts` file per guide topic, plus `index.ts` exporting `CONTENT_LISTINGS` and `getContentListingById`) - **Renderer:** `apps/docs/components/ContentListings/` (single `<ContentListings id="…" />` component); registered in `apps/docs/features/docs/MdxBase.shared.tsx` - **Types/helpers:** `apps/docs/lib/content-listings.schema.ts` (zod schemas, type aliases, grid/heading/href helpers) - **Markdown export:** `apps/docs/internals/markdown-schema/Listings.ts` (single ID-driven handler) wired into `apps/docs/internals/generate-guides-markdown.ts` - **Telemetry:** `docs_content_listing_clicked` defined in `packages/common/telemetry-constants.ts`, fired from `ContentListings.client.tsx` - **Authoring guide:** `apps/docs/CONTRIBUTING.md` (Components and elements → Content listings) - **VS Code snippets:** `.vscode/content-listing.code-snippets` (`cl-data`, `cl-inline`) ### Before & After #### Auth | [Before (production)](https://supabase.com/docs/guides/auth) | [After (preview)](https://docs-git-fork-nrichers-nikrichers-docs-1032-sta-e2a8cb-supabase.vercel.app/docs/guides/auth) | | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | |  |  | #### Database overview | [Before (production)](https://supabase.com/docs/guides/database/overview) | [After (preview)](https://docs-git-fork-nrichers-nikrichers-docs-1032-sta-e2a8cb-supabase.vercel.app/docs/guides/database/overview) | | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | |  |  | #### Edge Functions | [Before (production)](https://supabase.com/docs/guides/functions) | [After (preview)](https://docs-git-fork-nrichers-nikrichers-docs-1032-sta-e2a8cb-supabase.vercel.app/docs/guides/functions) | | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | |  |  | #### Storage | [Before (production)](https://supabase.com/docs/guides/storage) | [After (preview)](https://docs-git-fork-nrichers-nikrichers-docs-1032-sta-e2a8cb-supabase.vercel.app/docs/guides/storage) | | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | |  |  | #### Realtime | [Before (production)](https://supabase.com/docs/guides/realtime) | [After (preview)](https://docs-git-fork-nrichers-nikrichers-docs-1032-sta-e2a8cb-supabase.vercel.app/docs/guides/realtime) | | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | |  |  | #### Getting Started (partial migration for demoing) | [Before (production)](https://supabase.com/docs/guides/getting-started) | [After (preview)](https://docs-git-fork-nrichers-nikrichers-docs-1032-sta-e2a8cb-supabase.vercel.app/docs/guides/getting-started) | | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | |  |  | ### Test plan - [ ] Visually verify migrated pages render correctly: - [ ] `/guides/auth` — grid "Get started", conditional pricing list, grid "Next steps" - [ ] `/guides/database/overview` — get started + next steps listings - [ ] `/guides/getting-started` — top 3-column grid - [ ] `/guides/functions` — get started + example listings - [ ] `/guides/storage` — get started, examples, resources listings - [ ] `/guides/realtime` — get started, examples, resources listings - [ ] Confirm listings render at explicit page positions - [ ] Click a content listing link and verify `docs_content_listing_clicked` fires in PostHog with expected properties (the new `listingId` is the namespaced kebab-case id, e.g. `storage-get-started`) - [ ] Build docs and confirm `.md` alternate output includes listing sections at component placement (e.g. `public/markdown/guides/storage.md`) - [ ] Run unit tests: `pnpm test:local lib/content-listings.test.ts` in `apps/docs` ## Summary by CodeRabbit ## Release Notes * **New Features** * Introduced a standardized content listings system for organizing related guides and resources. * Content listings now support both grid and list layouts for consistent presentation. * Added click telemetry for content listing interactions. * **Documentation** * Updated authentication, database, functions, getting started, realtime, and storage guide pages to use the new content listing components. * Improved MDX structure examples and listing markup formatting in contributor documentation. <!-- end of auto-generated comment: release notes by coderabbit.ai --> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit ## Release Notes * **New Features** * Introduced a new content listings component for displaying guide content in list and grid layouts across documentation pages. * Added telemetry tracking for content listing interactions to measure user engagement. * **Documentation** * Updated guide pages (Authentication, Database, Functions, Storage, Realtime, Getting Started) to use the new listings layout. * Added contribution guidelines for creating and managing content listings in documentation. * **Tests** * Added comprehensive test coverage for content listings validation, serialization, and rendering. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Nik Richers <nik@validmind.ai> Co-authored-by: Jeremias Menichelli <jmenichelli@gmail.com> |
