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.
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>erss: trueno frontmatter (consulte Ativar comrss: 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.
| Atributo | Valores | Padrão | Finalidade |
|---|---|---|---|
data-base | URL do seu site | origem do script | A origem *.jamdesk.app (mais /docs se você hospedar em um subcaminho). |
data-page | Caminho | /changelog | Qualquer caminho da documentação para abrir no modal, não apenas /changelog. Consulte Direcionar o modal para qualquer página. |
data-theme | auto, light, dark | auto | Força o esquema de cores do modal ou segue a configuração do sistema do visitante. |
data-position | bottom-right, bottom-left, top-right, top-left | bottom-right | Define em qual canto fica o iniciador flutuante. Ignorado quando data-trigger está definido. |
data-label | Texto | What's new | Texto do botão do iniciador flutuante. |
data-width | Comprimento CSS | 560px | Largura do modal. Consulte Definir o tamanho do modal. |
data-height | Comprimento CSS | 680px | Altura do modal. |
data-radius | Comprimento CSS | 12px | Raio dos cantos do modal. Reduza o valor para deixar os cantos mais retos. |
data-unread | off para desativar | ativado | Define se o ponto de atualização não lida deve aparecer. |
data-unread-color | Cor hexadecimal ou nome de cor CSS | #e5484d | Cor do ponto de atualização não lida. |
data-button-color | Cor hexadecimal ou nome de cor CSS | #111 | Cor de fundo do iniciador flutuante. Ignorado quando data-trigger está definido. |
data-button-text-color | Cor hexadecimal ou nome de cor CSS | #fff | Cor do texto do iniciador flutuante. |
data-trigger | Seletor CSS | (nenhum) | Vincula o widget ao seu próprio elemento em vez de usar o iniciador flutuante. |
data-project | Slug | derivado de data-base | Chave 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 comdata-trigger. Seu elemento sempre será exibido.
Modos do launcher
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-srccarregawidget.js.frame-srcrenderiza o iframe do modal.connect-srcbusca 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?
