Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

fix(studio): reduce doc link density in auth email template builder (#47250)

Nik Richers32d1bdd534fd
diff --git a/apps/docs/content/guides/auth/auth-email-templates.mdx b/apps/docs/content/guides/auth/auth-email-templates.mdx
index 34fe78b1811..f963ef84647 100644
--- a/apps/docs/content/guides/auth/auth-email-templates.mdx
+++ b/apps/docs/content/guides/auth/auth-email-templates.mdx
@@ -49,7 +49,27 @@ The templating system provides the following variables for use:
## Editing email templates
-On hosted Supabase projects, edit your email templates on the [Email Templates](/dashboard/project/_/auth/templates) page. On self-hosted projects or in local development, edit your [configuration files](/docs/guides/local-development/customizing-email-templates).
+Where you edit templates depends on how you run Supabase.
+
+### Hosted projects
+
+Edit templates on the [Email Templates](/dashboard/project/_/auth/templates) page in the dashboard. The template builder uses the same [terminology](#terminology) and variables documented on this page.
+
+### Local development and self-hosted
+
+The dashboard template builder does not apply when running Supabase locally or self-hosted. Customize templates in `supabase/config.toml` and HTML files instead.
+
+<Admonition type="note" title="Customizing templates locally">
+
+See [Customizing email templates](/docs/guides/local-development/customizing-email-templates) for:
+
+- [`config.toml` keys and HTML file paths](/docs/guides/local-development/customizing-email-templates#configuring-templates)
+- [Template variables](/docs/guides/local-development/customizing-email-templates#template-variables) — the same placeholders as the [terminology](#terminology) table above
+- Default subjects and behavior for each [authentication](/docs/guides/local-development/customizing-email-templates#available-authentication-email-templates) and [security notification](/docs/guides/local-development/customizing-email-templates#available-security-notification-email-templates) template
+
+For production self-hosted deployments, see [Custom email templates](/docs/guides/self-hosting/custom-email-templates).
+
+</Admonition>
You can also manage email templates using the Management API:
diff --git a/apps/docs/content/guides/local-development/customizing-email-templates.mdx b/apps/docs/content/guides/local-development/customizing-email-templates.mdx
index 7316d957249..bc281e89d15 100644
--- a/apps/docs/content/guides/local-development/customizing-email-templates.mdx
+++ b/apps/docs/content/guides/local-development/customizing-email-templates.mdx
@@ -6,6 +6,8 @@ subtitle: 'Customize local email templates via the config file.'
You can customize the email templates for local development by [editing the `config.toml` file](/docs/guides/local-development/cli/config#auth-config).
+This guide covers local development and CLI workflows. For hosted projects, use the [Email Templates](/dashboard/project/_/auth/templates) page in the dashboard. See [Email templates](/docs/guides/auth/auth-email-templates) for terminology, limitations, and customization patterns that apply in every environment.
+
<Admonition type="note">
For configuring a self-hosted Supabase instance, see [Custom Email Templates](/docs/guides/self-hosting/custom-email-templates)
diff --git a/apps/studio/components/interfaces/Auth/EmailTemplates/EmailTemplates.constants.test.ts b/apps/studio/components/interfaces/Auth/EmailTemplates/EmailTemplates.constants.test.ts
index 0efbcd78e99..3df90628e9d 100644
--- a/apps/studio/components/interfaces/Auth/EmailTemplates/EmailTemplates.constants.test.ts
+++ b/apps/studio/components/interfaces/Auth/EmailTemplates/EmailTemplates.constants.test.ts
@@ -1,6 +1,9 @@
import { describe, expect, it } from 'vitest'
-import { EMAIL_TEMPLATE_DOCS_ANCHORS } from './EmailTemplates.constants'
+import {
+ AUTH_EMAIL_TEMPLATES_TERMINOLOGY_ANCHOR,
+ EMAIL_TEMPLATE_DOCS_ANCHORS,
+} from './EmailTemplates.constants'
import { AUTH_TEMPLATE_TYPES, type AuthTemplateType } from './EmailTemplates.types'
/** Docs section headings from customizing-email-templates.mdx */
@@ -32,6 +35,12 @@ function docsHeadingToAnchor(heading: string) {
.replace(/[ ]/g, '-')
}
+describe('EmailTemplates.constants: AUTH_EMAIL_TEMPLATES_TERMINOLOGY_ANCHOR', () => {
+ it('matches auth-email-templates.mdx heading slug', () => {
+ expect(AUTH_EMAIL_TEMPLATES_TERMINOLOGY_ANCHOR).toBe(docsHeadingToAnchor('Terminology'))
+ })
+})
+
describe('EmailTemplates.constants: EMAIL_TEMPLATE_DOCS_ANCHORS', () => {
it('covers every auth template type', () => {
expect(Object.keys(EMAIL_TEMPLATE_DOCS_ANCHORS).sort()).toEqual([...AUTH_TEMPLATE_TYPES].sort())
diff --git a/apps/studio/components/interfaces/Auth/EmailTemplates/EmailTemplates.constants.ts b/apps/studio/components/interfaces/Auth/EmailTemplates/EmailTemplates.constants.ts
index ad52828a963..060b381adac 100644
--- a/apps/studio/components/interfaces/Auth/EmailTemplates/EmailTemplates.constants.ts
+++ b/apps/studio/components/interfaces/Auth/EmailTemplates/EmailTemplates.constants.ts
@@ -8,6 +8,11 @@ import { getAuthTemplateType } from './EmailTemplates.utils'
export const AUTH_TEMPLATE_RESET_TYPES: AuthTemplateResetType[] =
AUTH_TEMPLATE_TYPES.map(getAuthTemplateType)
+/** Hosted email templates guide for dashboard users. */
+export const AUTH_EMAIL_TEMPLATES_DOCS_PATH = '/guides/auth/auth-email-templates'
+
+export const AUTH_EMAIL_TEMPLATES_TERMINOLOGY_ANCHOR = 'terminology'
+
/** Docs heading anchors for customizing-email-templates.mdx (ui Heading slugify output). */
export const EMAIL_TEMPLATE_DOCS_ANCHORS = {
CONFIRMATION: 'authemailtemplateconfirmation',
diff --git a/apps/studio/components/interfaces/Auth/EmailTemplates/TemplateEditor.tsx b/apps/studio/components/interfaces/Auth/EmailTemplates/TemplateEditor.tsx
index b24311c00da..49b2b65da68 100644
--- a/apps/studio/components/interfaces/Auth/EmailTemplates/TemplateEditor.tsx
+++ b/apps/studio/components/interfaces/Auth/EmailTemplates/TemplateEditor.tsx
@@ -23,6 +23,10 @@ import { Admonition } from 'ui-patterns'
import { FormItemLayout } from 'ui-patterns/form/FormItemLayout/FormItemLayout'
import z from 'zod'
+import {
+ AUTH_EMAIL_TEMPLATES_DOCS_PATH,
+ AUTH_EMAIL_TEMPLATES_TERMINOLOGY_ANCHOR,
+} from './EmailTemplates.constants'
import type { AuthTemplate } from './EmailTemplates.types'
import { hasCustomEmailSender } from './EmailTemplates.utils'
import { ResetTemplateDialog } from './ResetTemplateDialog'
@@ -366,15 +370,9 @@ export const TemplateEditor = ({ template, isReadOnly = false }: TemplateEditorP
<p className="text-sm text-foreground-lighter">
Data placeholders that can be inserted into the subject or body.{' '}
<InlineLink
- href={`${DOCS_URL}/guides/auth/auth-email-templates#terminology`}
- >
- Terminology
- </InlineLink>
- {' · '}
- <InlineLink
- href={`${DOCS_URL}/guides/local-development/customizing-email-templates#template-variables`}
+ href={`${DOCS_URL}${AUTH_EMAIL_TEMPLATES_DOCS_PATH}#${AUTH_EMAIL_TEMPLATES_TERMINOLOGY_ANCHOR}`}
>
- Local development
+ Learn more
</InlineLink>
</p>
</div>
diff --git a/apps/studio/pages/project/[ref]/auth/templates/[templateId].tsx b/apps/studio/pages/project/[ref]/auth/templates/[templateId].tsx
index 01346476643..ba1d3cc5196 100644
--- a/apps/studio/pages/project/[ref]/auth/templates/[templateId].tsx
+++ b/apps/studio/pages/project/[ref]/auth/templates/[templateId].tsx
@@ -44,7 +44,7 @@ import * as z from 'zod'
import { TEMPLATES_SCHEMAS } from '@/components/interfaces/Auth/EmailTemplates/AuthTemplatesValidation'
import { CustomEmailTemplateRestrictionAdmonition } from '@/components/interfaces/Auth/EmailTemplates/CustomEmailTemplateRestrictionAdmonition'
-import { EMAIL_TEMPLATE_DOCS_ANCHORS } from '@/components/interfaces/Auth/EmailTemplates/EmailTemplates.constants'
+import { AUTH_EMAIL_TEMPLATES_DOCS_PATH } from '@/components/interfaces/Auth/EmailTemplates/EmailTemplates.constants'
import {
isCustomEmailTemplateEditingRestricted,
isCustomEmailTemplateRestrictionStatusKnown,
@@ -54,7 +54,6 @@ import { TemplateEditor } from '@/components/interfaces/Auth/EmailTemplates/Temp
import AuthLayout from '@/components/layouts/AuthLayout/AuthLayout'
import { DefaultLayout } from '@/components/layouts/DefaultLayout'
import { DocsButton } from '@/components/ui/DocsButton'
-import { InlineLink } from '@/components/ui/InlineLink'
import { NoPermission } from '@/components/ui/NoPermission'
import { useAuthConfigQuery } from '@/data/auth/auth-config-query'
import { useAuthConfigUpdateMutation } from '@/data/auth/auth-config-update-mutation'
@@ -208,13 +207,8 @@ const RedirectToTemplates = () => {
{template.purpose || 'Configure and customize email templates.'}
</PageHeaderDescription>
</PageHeaderSummary>
- <PageHeaderAside className="flex items-center gap-3">
- <InlineLink href={`${DOCS_URL}/guides/auth/auth-email-templates#terminology`}>
- Terminology
- </InlineLink>
- <DocsButton
- href={`${DOCS_URL}/guides/local-development/customizing-email-templates#${EMAIL_TEMPLATE_DOCS_ANCHORS[template.id]}`}
- />
+ <PageHeaderAside>
+ <DocsButton href={`${DOCS_URL}${AUTH_EMAIL_TEMPLATES_DOCS_PATH}`} />
</PageHeaderAside>
</PageHeaderMeta>
</PageHeader>