Jamdesk Documentation logo

Incorporar uma página

Adicione ao seu app um botão “Novidades” que abre o changelog do Jamdesk em um modal e indica atualizações não lidas. Basta uma tag de script, sem etapa de build.

Adicione um acionador “What's new?” ao seu produto. Um botão ou iniciador flutuante abre as entradas do changelog da sua documentação em um modal. Um ponto indica atualizações não lidas para cada visitante. Basta colar uma tag <script>. O Jamdesk hospeda e versiona o widget.

O ponto de atualização não lida foi criado para o changelog. Ainda assim, o widget pode abrir qualquer página da documentação no modal. Consulte Direcionar o modal para qualquer página.

As capturas de tela mostram a interface em inglês.

O modal What's new aberto sobre um app escurecido, mostrando a página de changelog do Jamdesk com um botão Copy page e entradas de atualização datadas, além de um botão para fechar no canto superior

Teste ao vivo

Esta página executa o widget real. Clique no botão para abrir o modal que seus visitantes verão, carregado com o changelog deste site:

Esse botão é o componente MDX <Widget>. Use-o para incorporar o widget em uma página de documentação do Jamdesk. Ele usa uma única tag, não precisa de script e encontra seu site automaticamente. Use o trecho <script> abaixo para incorporar o widget no seu produto ou app, onde componentes MDX não são executados. O widget e o modal são os mesmos. O restante desta página aborda o script.

Pré-requisitos

  • Um site Jamdesk publicado no subdomínio *.jamdesk.app. O widget sempre carrega de lá, mesmo que você também disponibilize a documentação em um domínio personalizado.
  • Uma página de changelog criada com entradas <Update> e rss: true no frontmatter (consulte Ativar com rss: true).

Início rápido

Abra o dashboard e acesse Integrations → What's New widget. Defina as opções da página e do iniciador. Copie o trecho gerado. Ele será semelhante a este:

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-theme="auto"
  async
></script>

Cole-o no HTML do seu app, antes da tag de fechamento </body>. Ele adiciona um iniciador flutuante What's new no canto. O iniciador abre seu changelog em um modal. Um ponto de atualização não lida aparece quando há uma entrada que o visitante ainda não viu.

Substitua acme pelo seu próprio subdomínio. O cartão do dashboard preenche esse valor. Ele define data-base com a origem correta, incluindo o caminho /docs se você hospedar a documentação em um subcaminho.

Fixar uma versão ou hospedar localmente

O widget é de código aberto. O trecho hospedado acima sempre disponibiliza a versão mais recente. O repositório jamdesk-widget oferece outras duas maneiras de carregá-lo: fixar uma versão conhecida ou hospedar o arquivo por conta própria.

Fixe uma versão com jsDelivr. Carregue uma versão marcada do CDN. Os bytes não mudam:

<script
  src="https://cdn.jsdelivr.net/gh/jamdesk/jamdesk-widget@v1.0.0/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  async
></script>

Hospede por conta própria. Baixe widget.js da versão mais recente e disponibilize-o na sua própria origem. Use esta opção quando uma política script-src restrita impedir scripts de terceiros.

Defina data-base com a origem *.jamdesk.app ao usar um arquivo fixado ou hospedado por conta própria. O trecho hospedado obtém esse valor do próprio URL do script. Um CDN ou seu próprio servidor não consegue fazer isso. Cada versão publica um hash de Subresource Integrity para fixar os bytes exatos. O README do repositório descreve os três métodos de instalação.

Ative com rss: true

O widget lê a entrada mais recente do seu feed RSS. Uma página só fornece entradas ao widget quando o frontmatter define rss: true:

---
title: Changelog
rss: true
---

<Update label="June 2026" date="2026-06-01">

**Spec validation at build time.** Every deploy validates the OpenAPI specs your `docs.json` references.

</Update>

Sem rss: true, o widget carrega, mas não mostra entradas. O iniciador permanece oculto. Uma página da documentação que apenas demonstra o componente <Update> (sem rss: true) não é incluída. Uma data de demonstração não acende o ponto.

Cada <Update> que fornece conteúdo ao widget precisa de uma date (qualquer valor reconhecido por Date.parse, como 2026-06-01). Definir rss: true na página não basta. A data ordena o feed e identifica a entrada mais recente. O widget ignora entradas sem data. Sem entradas datadas, o iniciador flutuante permanece oculto e o ponto de atualização não lida nunca aparece, mesmo que rss: true esteja definido.

Configure o snippet

Cada opção é um atributo data- na tag do script. O cartão do dashboard os preenche. Você também pode editar o trecho manualmente.

AtributoValoresPadrãoFinalidade
data-baseURL do seu siteorigem do scriptA origem *.jamdesk.app (mais /docs se você hospedar em um subcaminho).
data-pageCaminho/changelogQualquer caminho da documentação para abrir no modal, não apenas /changelog. Consulte Direcionar o modal para qualquer página.
data-themeauto, light, darkautoForça o esquema de cores do modal ou segue a configuração do sistema do visitante.
data-positionbottom-right, bottom-left, top-right, top-leftbottom-rightDefine em qual canto fica o iniciador flutuante. Ignorado quando data-trigger está definido.
data-labelTextoWhat's newTexto do botão do iniciador flutuante.
data-widthComprimento CSS560pxLargura do modal. Consulte Definir o tamanho do modal.
data-heightComprimento CSS680pxAltura do modal.
data-radiusComprimento CSS12pxRaio dos cantos do modal. Reduza o valor para deixar os cantos mais retos.
data-unreadoff para desativarativadoDefine se o ponto de atualização não lida deve aparecer.
data-unread-colorCor hexadecimal ou nome de cor CSS#e5484dCor do ponto de atualização não lida.
data-button-colorCor hexadecimal ou nome de cor CSS#111Cor de fundo do iniciador flutuante. Ignorado quando data-trigger está definido.
data-button-text-colorCor hexadecimal ou nome de cor CSS#fffCor do texto do iniciador flutuante.
data-triggerSeletor CSS(nenhum)Vincula o widget ao seu próprio elemento em vez de usar o iniciador flutuante.
data-projectSlugderivado de data-baseChave usada para armazenar o estado de “visualizado” de cada visitante. Substitua-a somente se uma origem fornecer mais de um changelog.

Aponte o modal para qualquer página

data-page abre qualquer caminho do seu site de documentação, não apenas /changelog. O modal renderiza a página indicada sem os elementos de navegação do site. Use-o para um anúncio ou uma nota de migração:

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/announcements/2026-migration"
  data-unread="off"
  async
></script>

Dois comportamentos continuam vinculados ao feed do changelog:

  • O ponto de atualização não lida acompanha a entrada mais recente do changelog, não a página aberta no modal. Defina data-unread="off" quando o modal abrir outra página. Caso contrário, o ponto acenderá para atualizações do changelog que o visitante não verá nessa página.
  • O iniciador flutuante aparece somente quando há uma entrada no changelog (consulte Ativar com rss: true). Em um site sem changelog, vincule seu próprio elemento com data-trigger. Seu elemento sempre será exibido.

Modos do launcher

Iniciador flutuante

Deixe data-trigger desativado. O widget renderiza seu próprio botão no canto definido por data-position, com o texto de data-label.

Vincular ao seu próprio elemento

Defina data-trigger="#whats-new" (qualquer seletor CSS). O widget abre pelo link de navegação ou botão existente.

Um elemento vinculado recebe o ponto de atualização não lida. O widget não renderiza um botão flutuante, e data-position e data-label deixam de se aplicar:

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-trigger="#whats-new"
  async
></script>

Dimensione o modal

O modal abre com 560 × 680 px. Altere o tamanho com data-width e data-height. Um número sem unidade é interpretado como pixels. Também funcionam valores com px, vw, vh, rem, em ou %:

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-width="720px"
  data-height="600px"
  async
></script>

A largura do modal é limitada a 92vw e a altura, a 86vh. Mesmo um tamanho grande cabe na tela de um celular. Um valor não reconhecido retorna ao padrão. Por padrão, os cantos têm raio de 12px. Deixe-os retos ou mais arredondados com data-radius (qualquer comprimento CSS).

Estilize o botão do launcher

Por padrão, o iniciador flutuante é uma cápsula escura. Altere suas cores com data-button-color (fundo) e data-button-text-color (texto). Use um valor hexadecimal ou um nome de cor CSS:

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-button-color="#4f46e5"
  data-button-text-color="#ffffff"
  async
></script>

Esses dois atributos estilizam apenas o botão flutuante do próprio widget. Eles não afetam um elemento vinculado com data-trigger. Esse elemento mantém seu próprio estilo.

Personalize o indicador de não lidos

O ponto de atualização não lida é vermelho (#e5484d) e fica ativado por padrão. Altere sua cor com data-unread-color (um valor hexadecimal ou um nome de cor CSS). Desative-o com data-unread="off":

<!-- Recolor the dot -->
<script src="https://acme.jamdesk.app/_jd/widget.js" data-base="https://acme.jamdesk.app" data-unread-color="#7c3aed" async></script>

<!-- Turn the dot off -->
<script src="https://acme.jamdesk.app/_jd/widget.js" data-base="https://acme.jamdesk.app" data-unread="off" async></script>

Desativar o ponto não remove o iniciador nem o modal. Apenas o indicador é removido.

O indicador de não lidos

O widget compara o ID da entrada mais recente com um valor em localStorage do navegador (uma chave por projeto). Um ponto aparece no iniciador quando os valores são diferentes. Ao abrir o modal, a entrada é marcada como visualizada. O ponto permanece apagado até a próxima atualização ser publicada.

O estado fica em localStorage, por navegador e visitante. Não há conta nem rastreamento. Limpar os dados do site redefine o estado. Um visitante em um navegador novo vê o ponto uma vez. Ele volta a aparecer quando você publica algo novo.

Exemplos

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-position="bottom-left"
  data-unread-color="#22c55e"
  async
></script>

Content-Security-Policy

Se seu site enviar uma política Content-Security-Policy restrita, permita a origem *.jamdesk.app em três diretivas. Caso contrário, o widget não fará nada e não exibirá mensagens:

Content-Security-Policy:
  script-src  https://acme.jamdesk.app;
  frame-src   https://acme.jamdesk.app;
  connect-src https://acme.jamdesk.app;
  • script-src carrega widget.js.
  • frame-src renderiza o iframe do modal.
  • connect-src busca os metadados do changelog para o ponto de atualização não lida.

A ausência de uma diretiva não exibe um aviso de erro. O iniciador não aparecerá ou o modal ficará em branco. Se o widget não aparecer, verifique no console do navegador se há violações de CSP.

Sites protegidos por senha

Não incorpore o widget se seu site de documentação for protegido por senha. A tela de desbloqueio deve ficar no seu site *.jamdesk.app, não dentro de um iframe de terceiros. Incorporá-la pede aos visitantes que digitem a senha do seu site em um frame de outra origem. Isso parece uma tentativa de phishing. Use o widget somente para changelogs públicos.

O que vem a seguir?

Componente Update

Escreva as entradas do changelog que o widget lê

Domínios personalizados

Disponibilize a documentação no seu próprio domínio (o widget continuará carregando de jamdesk.app)

Código-fonte do widget

Fixe uma versão, hospede o widget por conta própria ou consulte o código-fonte no GitHub