From 0d465e7b5fb5c166e3887c6e7aad4afe8eece3b4 Mon Sep 17 00:00:00 2001 From: Miranda Limonczenko Date: Wed, 29 Jul 2026 09:26:50 -0700 Subject: [PATCH 1/7] chore(ui): Remove 'tip' from Admonition (#48419) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes FE-3966 ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## Problem - The admonition uses both 'tip' and 'note', but the visual distinction has long-ago collapsed. - 'Note' is used far more frequently than 'tip' - The two are very similar and it is confusing to know which one to use when they are visually identical ## Solution Collapse 'tip' and 'note' into one by removing all places where there is 'tip' and updating all references to 'tip' into 'note'. **Note:** This PR also resolves new broken links flagged by the E2E docs checker. It may move to another PR since E2Es keep erroring. ### Specific changes See below for an AI-generated list of changes: - **Type system** — removed `'tip'` from `AdmonitionType`, its `TYPE_TO_VARIANT`/`TYPE_LABEL` entries, and the test case in [`packages/ui-patterns/src/Admonition/](packages/ui-patterns/src/Admonition/) - **Remark plugin** — [remarkAdmonition.ts](apps/docs/lib/mdx/plugins/remarkAdmonition.ts) now maps mkdocs `tip` → `note` - **Lint allowlist** — `tip` dropped from `supa-mdx-lint.config.toml` - **Content migration** — all 109 files with `type="tip"` (across `apps/docs`, `apps/www`, `apps/studio`) converted to `type="note"`; zero remaining hits confirmed by repo-wide grep - **Style guide** — `CONTRIBUTING.md` and `contributing/content.mdx` updated to describe 4 admonition types instead of 5 ### Usage before implementation See the usage table that points toward 'note' as being dominant across all apps: Here's the usage table: | Location | `note` | `tip` | |---|---|---| | apps/docs | ~480 | ~143 | | apps/studio | 34 | 6 | | apps/www (blog) | 19 | 3 | | packages/ui-patterns (tests) | 3 | 1 (parametrized) | | design-system / ui-library / packages/ui / packages/common | 0–1 (test fixture only) | 0 | ## Preview links | App | Page | Search text (Ctrl+F) | Verify | |---|---|---|---| | docs | [/docs/guides/ai-tools/byo-mcp](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/ai-tools/byo-mcp) | official MCP TypeScript SDK | callout's aria-label="Note" | | docs | [/docs/guides/ai-tools/mcp](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/ai-tools/mcp) | MCP server is available at | callout's aria-label="Note" | | docs | [/docs/guides/ai/python-clients](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/ai/python-clients) | Click Connect at the top of any project page | callout's aria-label="Note" | | docs | [/docs/guides/auth/audit-logs](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/auth/audit-logs) | Disabling Postgres storage reduces your database storage costs | callout's aria-label="Note" | | docs | [/docs/guides/database/tables](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/database/tables) | access a custom schema through the Supabase Data API | callout's aria-label="Note" | | docs | [/docs/guides/troubleshooting/edge-function-404-error-response](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/troubleshooting/edge-function-404-error-response) | Always configure an appropriate time frame | callout's aria-label="Note" (was single-quoted type='tip') | | www | [blog: cli-v2-config-as-code](https://zone-www-dot-com-git-admonition-collapse-note-tip-supabase.vercel.app/blog/cli-v2-config-as-code) | Detecting config drift | callout's aria-label="Note" | | www | [blog: cli-v2-config-as-code](https://zone-www-dot-com-git-admonition-collapse-note-tip-supabase.vercel.app/blog/cli-v2-config-as-code) | Setting Edge Function secrets | callout's aria-label="Note" | | www | [blog: nosql-mongodb-compatibility-with-ferretdb-and-flydotio](https://zone-www-dot-com-git-admonition-collapse-note-tip-supabase.vercel.app/blog/nosql-mongodb-compatibility-with-ferretdb-and-flydotio) | If your network supports IPv6 connections | callout's aria-label="Note" | Note: the `www` rows use the `zone-www-dot-com` preview host, not the `docs` one you gave — since blog pages are served from the www app, not docs. ## Manual testing 1. Open preview links for affected pages. 2. Inspect. Open console. 3. Paste the following in and see there is no 'Tip' on the page: ``` document.querySelectorAll('[role="alert"]').forEach(el => console.log(el.getAttribute('aria-label'), el.textContent.slice(0,60))) ``` ## Summary by CodeRabbit * **Documentation** * Standardized informational callouts across docs and tutorials from **“Tip”** to **“Note”**, updating multiple examples and guidance blocks. * Updated a few related doc references/links and conditional “Next steps” content. * **UI Updates** * Switched various in-app banners and notices to the **“Note”** style variant. * **Bug Fixes / Improvements** * Removed support for the retired **“Tip”** callout type and aligned docs linting, component behavior, and aria labeling to the remaining admonition types. --- apps/docs/CONTRIBUTING.md | 3 +-- apps/docs/app/contributing/content.mdx | 19 +++---------------- .../WrapperDashboardIntegration.tsx | 2 +- apps/docs/content/_partials/api_settings.mdx | 2 +- apps/docs/content/_partials/cost_warning.mdx | 2 +- .../_partials/create_client_snippet.mdx | 2 +- .../_partials/postgres_installation.mdx | 2 +- apps/docs/content/_partials/providers.mdx | 2 +- .../content/_partials/quickstart_db_setup.mdx | 6 +++--- apps/docs/content/_partials/uiLibCta.mdx | 2 +- apps/docs/content/guides/ai-tools/byo-mcp.mdx | 2 +- apps/docs/content/guides/ai-tools/mcp.mdx | 8 ++++---- .../docs/content/guides/ai/python-clients.mdx | 2 +- .../guides/ai/rag-with-permissions.mdx | 6 +++--- .../docs/content/guides/ai/vector-columns.mdx | 6 +++--- apps/docs/content/guides/api.mdx | 2 +- .../api/handling-errors-in-supabase-js.mdx | 2 +- apps/docs/content/guides/auth/audit-logs.mdx | 2 +- apps/docs/content/guides/auth/auth-mfa.mdx | 2 +- .../content/guides/auth/auth-mfa/totp.mdx | 2 +- .../auth/enterprise-sso/auth-sso-saml.mdx | 6 +++--- .../auth/oauth-server/getting-started.mdx | 4 ++-- .../auth/oauth-server/mcp-authentication.mdx | 2 +- .../guides/auth/oauth-server/oauth-flows.mdx | 4 ++-- apps/docs/content/guides/auth/passwords.mdx | 14 +++++++------- apps/docs/content/guides/auth/server-side.mdx | 2 +- .../auth/server-side/advanced-guide.mdx | 2 +- .../docs/content/guides/auth/social-login.mdx | 2 +- .../guides/auth/social-login/auth-apple.mdx | 4 ++-- .../guides/auth/social-login/auth-azure.mdx | 2 +- .../auth/social-login/auth-facebook.mdx | 8 ++++---- .../guides/auth/social-login/auth-kakao.mdx | 2 +- .../guides/auth/social-login/auth-workos.mdx | 4 ++-- .../database/custom-postgres-config.mdx | 2 +- .../content/guides/database/import-data.mdx | 2 +- .../database/postgres/data-deletion.mdx | 4 ++-- .../guides/database/postgres/indexes.mdx | 2 +- .../postgres/setup-replication-external.mdx | 2 +- .../guides/database/postgres/timeouts.mdx | 2 +- apps/docs/content/guides/database/prisma.mdx | 2 +- .../guides/database/replication/pipelines.mdx | 2 +- apps/docs/content/guides/database/tables.mdx | 2 +- apps/docs/content/guides/deployment.mdx | 2 +- .../deployment/branching/configuration.mdx | 6 +++--- .../guides/deployment/database-migrations.mdx | 4 ++-- .../guides/deployment/going-into-prod.mdx | 4 ++-- .../deployment/managing-environments.mdx | 4 ++-- .../content/guides/functions/ai-models.mdx | 2 +- .../guides/functions/auth-legacy-jwt.mdx | 2 +- apps/docs/content/guides/functions/cors.mdx | 2 +- apps/docs/content/guides/functions/deploy.mdx | 2 +- .../elevenlabs-generate-speech-stream.mdx | 6 +++--- .../examples/elevenlabs-transcribe-speech.mdx | 2 +- .../guides/functions/quickstart-dashboard.mdx | 2 +- .../content/guides/functions/quickstart.mdx | 6 +++--- .../guides/getting-started/api-keys.mdx | 2 +- .../getting-started/quickstarts/kotlin.mdx | 2 +- .../getting-started/quickstarts/nuxtjs.mdx | 2 +- .../getting-started/quickstarts/redwoodjs.mdx | 6 +++--- .../getting-started/quickstarts/refine.mdx | 2 +- .../tutorials/with-angular.mdx | 2 +- .../getting-started/tutorials/with-nextjs.mdx | 2 +- .../getting-started/tutorials/with-react.mdx | 2 +- .../getting-started/tutorials/with-svelte.mdx | 2 +- .../tutorials/with-sveltekit.mdx | 4 ++-- .../partner-integration-guide.mdx | 2 +- .../local-development/cli-workflows.mdx | 4 ++-- .../local-development/cli/getting-started.mdx | 2 +- .../local-development/database-migrations.mdx | 2 +- .../declarative-database-schemas.mdx | 2 +- .../seeding-your-database.mdx | 6 +++--- .../migrating-to-supabase/postgres.mdx | 2 +- .../read-replicas/getting-started.mdx | 4 ++-- apps/docs/content/guides/platform/sso.mdx | 4 ++-- .../content/guides/platform/sso/azure.mdx | 2 +- .../platform/sso/choosing-login-flow.mdx | 4 ++-- .../content/guides/platform/sso/gsuite.mdx | 6 +++--- .../guides/platform/sso/login-flows.mdx | 4 ++-- .../platform/sso/multiple-providers.mdx | 2 +- .../docs/content/guides/platform/sso/okta.mdx | 6 +++--- .../platform/sso/testing-best-practices.mdx | 2 +- .../content/guides/platform/upgrading.mdx | 2 +- .../docs/content/guides/queues/quickstart.mdx | 4 ++-- apps/docs/content/guides/realtime/limits.mdx | 2 +- .../guides/realtime/postgres-changes.mdx | 4 ++-- apps/docs/content/guides/realtime/reports.mdx | 2 +- .../content/guides/security/npm-security.mdx | 2 +- .../self-hosting/copy-from-platform-s3.mdx | 2 +- .../self-hosting/custom-email-templates.mdx | 2 +- .../content/guides/self-hosting/docker.mdx | 4 ++-- .../self-hosting/remove-superuser-access.mdx | 4 ++-- .../self-hosting/restore-from-platform.mdx | 2 +- .../self-hosting/self-hosted-proxy-https.mdx | 2 +- .../self-hosting/self-hosted-saml-sso.mdx | 4 ++-- .../content/guides/storage/debugging/logs.mdx | 2 +- .../storage/management/download-objects.mdx | 2 +- .../storage/vector/querying-vectors.mdx | 2 +- .../telemetry/metrics/grafana-self-hosted.mdx | 2 +- ...imeouts-in-long-running-queries-6nmbdN.mdx | 4 ++-- .../edge-function-404-error-response.mdx | 2 +- .../content/troubleshooting/exhaust-swap.mdx | 2 +- ...ng-anon-service-and-jwt-secrets-1Jq6yd.mdx | 2 +- .../unable-to-call-edge-function.mdx | 2 +- apps/docs/lib/mdx/plugins/remarkAdmonition.ts | 3 +-- .../AccessTokenNewBanner.tsx | 2 +- .../OAuthApps/OAuthServerSettingsForm.tsx | 2 +- .../CreateQueueSheet/PgPartmanCallout.tsx | 2 +- .../SQLEditor/UtilityPanel/ChartConfig.tsx | 2 +- apps/studio/components/ui/AlphaNotice.tsx | 2 +- .../pages/partners/stripe/projects/login.tsx | 2 +- ...mpatibility-with-ferretdb-and-flydotio.mdx | 2 +- .../2024-12-04-cli-v2-config-as-code.mdx | 4 ++-- .../src/Admonition/Admonition.constants.ts | 2 -- .../src/Admonition/Admonition.test.tsx | 1 - .../src/Admonition/Admonition.types.ts | 1 - supa-mdx-lint.config.toml | 2 +- 116 files changed, 170 insertions(+), 189 deletions(-) diff --git a/apps/docs/CONTRIBUTING.md b/apps/docs/CONTRIBUTING.md index fac90e1aa4706..41cb00108b413 100644 --- a/apps/docs/CONTRIBUTING.md +++ b/apps/docs/CONTRIBUTING.md @@ -191,8 +191,7 @@ Choose the appropriate `type` for your admonition: - `danger`: Warn about actions or conditions that could cause data loss, expose sensitive data, or create another severe and difficult-to-reverse outcome. State the consequence first, and then explain how to avoid it. - `deprecation`: Identify a deprecated feature or behavior. State how the change affects the reader, and then provide the supported alternative or migration path. - `caution`: Warn about behavior that could cause bugs, failed operations, unexpected results, or serious inconvenience but doesn't rise to the severity of `danger`. -- `tip`: Share an optional shortcut, optimization, or best practice that helps the reader complete the task more effectively. The main procedure must still work without it. -- `note`: Highlight an important prerequisite, constraint, or clarification that doesn't represent a risk. If the information is essential to completing a step, include it in the procedure instead. +- `note`: Highlight an important prerequisite, constraint, clarification, or optional shortcut that doesn't represent a risk. If the information is essential to completing a step, include it in the procedure instead. ``` diff --git a/apps/docs/app/contributing/content.mdx b/apps/docs/app/contributing/content.mdx index 12d02b26a597a..a310714f4a360 100644 --- a/apps/docs/app/contributing/content.mdx +++ b/apps/docs/app/contributing/content.mdx @@ -75,12 +75,11 @@ For content that requires progressive disclosure: ### Admonition -For extra information that doesn't fit into the main flow. There are 5 supported types of admonitions: +For extra information that doesn't fit into the main flow, you can use the following types of admonitions: - `danger` to warn the user about any missteps that could cause data loss or data leaks - `deprecation` to notify the user about features that are (or will soon be) deprecated - `caution` to warn about anything that could cause a bug or serious user inconvenience -- `tip` to point out helpful but optional actions - `note` for anything else Leave a blank line between the admonition tag and the contained content. This will prevent Prettier from trying to break the lines within the content. @@ -104,15 +103,9 @@ You should make sure you don't set this up wrong. - - -In certain cases, you may want to do this. - - - -Additional helpful information. +In certain cases, you may want to do this. ``` @@ -135,15 +128,9 @@ You should make sure you don't set this up wrong. - - -In certain cases, you may want to do this. - - - -Additional helpful information. +In certain cases, you may want to do this. diff --git a/apps/docs/components/WrapperDashboardIntegration.tsx b/apps/docs/components/WrapperDashboardIntegration.tsx index 4e423f93b2aa8..d48058c51b1c5 100644 --- a/apps/docs/components/WrapperDashboardIntegration.tsx +++ b/apps/docs/components/WrapperDashboardIntegration.tsx @@ -4,7 +4,7 @@ import { Admonition } from 'ui-patterns/Admonition' export function WrapperDashboardIntegration({ title, path }: { title: string; path: string }) { return ( - +

You can enable the {title} wrapper right from the Supabase dashboard.