EmailSubscribe: inscrição

<EmailSubscribe> adiciona um formulário de inscrição por e-mail diretamente a uma página de documentação usando uma única tag MDX. Depois de conectar um provedor no dashboard, ele renderiza um formulário hospedado pela Jamdesk que envia novos inscritos diretamente para seu público. Sem um provedor conectado, ele também pode hospedar o embed de outra plataforma. O componente foi criado para páginas de changelog e notas de versão, nas quais os leitores querem saber o que há de novo.

Início rápido

Conecte primeiro um provedor no dashboard e, em seguida, adicione a tag com o id desse provedor:

<EmailSubscribe provider="resend" />

Isso renderiza um campo de e-mail identificado e um botão Subscribe. Ao enviar, o endereço é adicionado ao público que você conectou. A mesma tag funciona com qualquer provedor nativo (mailchimp, kit, loops, beehiiv, brevo ou sendgrid) depois que ele for conectado.

Adicione um título opcional e uma linha de apoio:

<EmailSubscribe
  provider="resend"
  title="Get release notes"
  description="One email when we ship something new. No spam."
/>

Propriedades

Nativo vs. embed

O provider informado determina o comportamento do formulário:

• 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 sua chave conectada. Esse é o caminho que exige um provedor conectado no dashboard.
• Provedores que aceitam apenas embed (buttondown, substack) renderizam o próprio formulário ou iframe do serviço. Não é necessário conectar uma chave: informe seu username e o visitante enviará os dados diretamente ao provedor.

Provedores que aceitam apenas embed

Buttondown e Substack funcionam sem uma conexão com o dashboard. Informe o nome de usuário da sua conta:

<EmailSubscribe provider="buttondown" username="acme" />
<EmailSubscribe provider="substack" username="acme" />

Alternativa flexível: cole qualquer embed

Para um provedor que não tenha uma abreviação na Jamdesk, cole a marcação do embed em snippet. Ela será renderizada como está na página publicada:

<EmailSubscribe snippet={`<form action="https://example.com/subscribe">...</form>`} />

Modo compacto

Um campo de e-mail completo e um botão Subscribe ocupam bastante espaço quando inseridos no meio de uma página. Defina collapsed para que o formulário nativo comece apenas como um botão Subscribe. Quando o leitor clicar nele, o campo completo será exibido diretamente na página, sem recarregá-la:

<EmailSubscribe provider="resend" collapsed title="Subscribe to updates" />

O rótulo do botão vem de title (ele usa "Subscribe to updates" como alternativa quando nenhum título é definido). Esse recurso funciona apenas com provedores nativos. Os provedores de embed renderizam a própria marcação, portanto a Jamdesk não tem nada para compactar.

Inscritos recorrentes

Depois que um leitor se inscreve por meio de um formulário nativo, o navegador se lembra disso. Na próxima visita, em vez do formulário completo, ele verá uma linha curta: You're subscribed to the newsletter. Ninguém será convidado a se inscrever novamente em algo que já assinou.

Se quiser adicionar um segundo endereço, o leitor encontrará um controle "Use a different email?" que reabre o formulário completo imediatamente. Essa informação é armazenada por navegador (em localStorage, não no seu público); portanto, limpar os dados do site ou trocar de navegador fará o formulário aparecer novamente. Não é necessário configurar nada: todo formulário nativo funciona assim.

Posicionamento automático em páginas de changelog

Em vez de adicionar a tag manualmente a cada página de versão, monte o formulário automaticamente nas páginas de changelog. Em docs.json, defina placement como changelog na integração de newsletter:

{
  "integrations": {
    "newsletter": {
      "provider": "resend",
      "title": "Get release notes",
      "placement": "changelog"
    }
  }
}

Com placement: "changelog", o formulário é montado em todas as páginas de changelog (qualquer página com rss: true). Para ignorá-lo em uma dessas páginas, defina newsletter: false no frontmatter da página. Se uma página já tiver um <EmailSubscribe> adicionado manualmente, o posicionamento automático dará preferência a ele, evitando a exibição de dois formulários.

O bloco completo integrations.newsletter aceita os mesmos campos do componente (provider, title, description, collapsed, username, snippet, height), além de placement (none, o valor padrão, ou changelog).

O que vem a seguir?