EmailSubscribe
Adicione um formulário de inscrição em newsletter ou changelog a qualquer página de documentação com o componente EmailSubscribe: captura nativa para sete provedores e embeds para os demais.
<EmailSubscribe> exibe um formulário de inscrição por e-mail diretamente em uma página de documentação. Com um provedor conectado no painel, ele renderiza um formulário hospedado pela Jamdesk que adiciona novos assinantes à sua audiência. Sem um provedor, pode hospedar o embed de outro serviço. Use-o em páginas de changelog e notas de versão.
Início rápido
Conecte um provedor no painel. Em seguida, adicione a tag com o id desse provedor:
<EmailSubscribe provider="resend" />
Isso renderiza um campo de e-mail com rótulo e um botão Subscribe. A Jamdesk adiciona cada endereço enviado à audiência que você conectou. A mesma tag funciona com qualquer provedor nativo conectado (mailchimp, kit, loops, beehiiv, brevo ou sendgrid).
Adicione um título e uma linha de apoio opcionais:
<EmailSubscribe
provider="resend"
title="Get release notes"
description="One email when we ship something new. No spam."
/>
Propriedades
| Prop | Tipo | Finalidade |
|---|---|---|
provider | string | Id do provedor: resend, mailchimp, kit, loops, beehiiv, brevo, sendgrid, buttondown ou substack. |
title | string | Título opcional exibido acima do formulário. |
description | string | Linha de apoio opcional abaixo do título. |
collapsed | boolean | Apenas provedores nativos. Começa como um botão Subscribe compacto que expande para o formulário completo ao clicar. |
username | string | Nome de usuário da conta Buttondown / Substack (provedores somente de embed). |
snippet | string | Marcação de embed bruta de qualquer provedor. A saída de emergência (veja abaixo). |
className | string | Classe CSS extra no wrapper. |
Nativo vs. embed
O provider que você passa define como o formulário se comporta:
- Provedores nativos (
resend,mailchimp,kit,loops,beehiiv,brevo,sendgrid) renderizam um formulário hospedado pela Jamdesk. A Jamdesk captura o endereço e o adiciona usando a chave conectada. Eles exigem um provedor conectado no painel. - Provedores somente de embed (
buttondown,substack) renderizam o formulário ou iframe próprio desse serviço. Você não conecta nenhuma chave. Passe seuusername. O visitante envia diretamente ao provedor.
Um provedor nativo que não está conectado no painel não captura nada. Conecte o provedor primeiro.
Provedores que aceitam apenas embed
Buttondown e Substack funcionam sem conexão no painel. Passe o nome de usuário da sua conta:
<EmailSubscribe provider="buttondown" username="acme" />
<EmailSubscribe provider="substack" username="acme" />
Alternativa flexível: cole qualquer embed
Cole a marcação de embed de qualquer provedor em snippet. Ela é renderizada como está na página publicada:
<EmailSubscribe snippet={`<form action="https://example.com/subscribe">...</form>`} />
Um snippet executa o código próprio do provedor na sua página. Alguns provedores usam um script de execução única que não é executado novamente quando o leitor navega entre páginas sem um recarregamento completo. Coloque embeds baseados em script em uma página dedicada e carregada diretamente (como seu changelog), em vez de no meio de um fluxo de navegação.
Modo compacto
Defina collapsed para iniciar o formulário nativo como um botão Subscribe. Ao clicar, o campo completo abre na própria página, sem recarregá-la:
<EmailSubscribe provider="resend" collapsed title="Subscribe to updates" />
O rótulo do botão vem de title. O padrão é "Subscribe to updates". O modo compacto é exclusivo de provedores nativos. Provedores de embed renderizam a própria marcação.
Inscritos recorrentes
O navegador lembra de um leitor que assinou por um formulário nativo. Na próxima visita, o leitor vê uma linha curta em vez do formulário: You're subscribed to the newsletter.
A linha tem um controle "Use a different email?" que reabre o formulário completo. A memória é por navegador. Ela fica em localStorage, não na sua audiência. Limpar os dados do site ou trocar de navegador faz o formulário aparecer novamente. Formulários nativos fazem isso sem nenhuma configuração.
Posicionamento automático em páginas de changelog
Monte o formulário nas páginas de changelog sem adicionar a tag manualmente. Defina o placement da integração de newsletter como changelog em docs.json:
{
"integrations": {
"newsletter": {
"provider": "resend",
"title": "Get release notes",
"placement": "changelog"
}
}
}
O formulário é então montado em todas as páginas de changelog (qualquer página com rss: true). Ignore-o em uma página específica com newsletter: false no frontmatter dessa página. Uma página com um <EmailSubscribe> posicionado manualmente não recebe um segundo formulário.
O bloco completo integrations.newsletter aceita os mesmos campos do componente (provider, title, description, collapsed, username, snippet, height) além de placement (none, o padrão, ou changelog).
O cartão Email Signups no painel tem os campos Form title e Form subtitle. Um formulário posicionado automaticamente os usa quando o docs.json omite title e description. Defina title/description no docs.json apenas para substituir o texto do painel.
