Widgets de conteúdo

Transforma listas de links em uma grade responsiva. Ideal para páginas de índice e páginas centrais que encaminham os leitores para outro lugar.

• Cada título se torna um pequeno rótulo em maiúsculas acima da sua grade. Os títulos são opcionais.
• - [Title](/href) — Description. cria um cartão com um título e uma descrição.
• Termine um item com {icon-name} para adicionar um ícone, por exemplo, {rocket}, {book-open}. Os nomes vêm do conjunto Lucide. Um nome desconhecido é descartado silenciosamente — as chaves nunca chegam à página.
• Coloque uma imagem ![alt](https://raw.githubusercontent.com/docsbook-io/docs/main/content/features/url) no item para usar uma imagem real em vez de um ícone — ela preenche a mesma área que o ícone ocuparia. É melhor do que um ícone quando o cartão trata de algo específico que você tem em uma imagem.
• Um item sem link é renderizado como um cartão não clicável.

<!-- widget:cards -->
 
## Start here
 
- [Search](/docsbook-io/docs/content/features/search) — Let readers find a page by keyword {search}
- [Page feedback](/docsbook-io/docs/content/features/feedback) — Ask whether the page helped {thumbs-up}
 
<!-- /widget -->

Dê um corpo ao cartão. Deixe uma linha em branco após o item e indente mais markdown sob ele — parágrafos, uma lista curta, um trecho. Ele é renderizado abaixo da descrição. Vale a pena quando o cartão tem algo a explicar; um cartão que apenas identifica um destino fica melhor em uma linha.

Dê ao cartão sua própria ação. Se a última linha indentada contiver apenas links, ela se tornará a linha de chamada para ação do cartão. Uma frase que apenas contém um link continua sendo um texto comum.

Escolha o layout. cols=1, cols=2, cols=3 ou cols=4 fixa o número de colunas; horizontal coloca o ícone ao lado do texto em vez de acima dele, para uma linha compacta. Ambos ficam no marcador de abertura e podem ser combinados. Sem cols, a grade comporta tantos cartões por linha quanto a largura da página permitir, que geralmente é o que você deseja. Telas estreitas sempre terão menos colunas.

<!-- widget:cards cols=2 -->
 
- [Full-text search](/docsbook-io/docs/content/features/search) — Match a reader's keyword against your pages {search}
 
  Indexes every markdown file the site publishes and rebuilds itself when the
  repository changes. Nothing to reindex by hand.
 
  [Read the guide](/docsbook-io/docs/content/features/search)
 
- [Page feedback](/docsbook-io/docs/content/features/feedback) — Ask whether the page helped {thumbs-up}
 
  One click from the reader, no form and no email address. Results land per
  page, so you can sort by the pages rated worst.
 
  [Read the guide](/docsbook-io/docs/content/features/feedback)
 
<!-- /widget -->

Transforma seções com título em uma faixa de abas com um painel visível. Use quando a mesma instrução existir em várias versões paralelas e o leitor precisar exatamente de uma delas: um gerenciador de pacotes, um sistema operacional, um SDK de linguagem, um caminho hospedado ou autogerenciado.

• Cada título se torna uma aba; tudo o que estiver abaixo dele até o próximo título do mesmo nível se torna o painel dessa aba.
• A primeira aba é a que abre, então coloque primeiro a variante que a maioria dos leitores deseja.
• Um título pode terminar com {icon-name}, por exemplo, ### macOS {apple}. Dê um ícone a todas as abas ou a nenhuma — uma faixa em que apenas algumas abas têm ícone parece quebrada.
• Qualquer Markdown funciona dentro de um painel, incluindo tabelas e blocos de código com realce de sintaxe.
• O conteúdo antes do primeiro título é exibido acima da faixa como uma introdução. Use-o para a frase que é verdadeira para todas as abas.
• Mantenha os rótulos com uma ou duas palavras. A faixa rola lateralmente em vez de quebrar linha, portanto um rótulo do tamanho de uma frase empurra as outras abas para fora da tela.
• Até 8 abas podem ser alternadas. Uma 9ª seção e as seguintes são exibidas abaixo da faixa como títulos comuns — nada é perdido, mas um conjunto tão longo deveria usar uma lista de títulos.
• Todos os painéis estão no código-fonte da página e a alternância usa apenas CSS, portanto todas as variantes continuam legíveis com o JavaScript desativado e visíveis para os rastreadores.

Não use isso para ocultar conteúdo de que o leitor precisa por completo. Isso é accordion em material de referência consultado rapidamente, e títulos simples para uma sequência.

Transforma seções com título em linhas que o leitor expande. Ideal para conteúdo que as pessoas percorrem em vez de ler: perguntas frequentes, solução de problemas e detalhes por opção.

• Cada título se torna uma linha; tudo o que estiver abaixo dele até o próximo título do mesmo nível se torna o corpo da linha.
• Qualquer Markdown funciona dentro de uma linha, incluindo blocos de código e tabelas.
• Todas as linhas começam recolhidas, portanto escreva títulos que forneçam informações suficientes para a escolha sem precisar abri-los.
• O conteúdo antes do primeiro título é exibido acima do accordion como uma introdução.

Transforma seções com título em uma sequência conectada, de cima para baixo. Use quando a ordem for importante — instalação, configuração ou um tutorial em várias etapas. Se a ordem não importar, use accordion.

• Cada título se torna uma etapa, numerada na ordem do documento.
• Adicionar ou remover uma etapa renumera automaticamente as demais.

Transforma planos em uma linha de cartões comparáveis ou uma tabela de planos em uma matriz de comparação. Use quando o leitor precisar escolher entre níveis, em vez de ler sobre eles.

O widget escolhe seu formato com base no que você escreveu: a presença de títulos gera um cartão por plano; uma região que seja apenas uma tabela simples é renderizada novamente como uma matriz. Escreva usando o formato que a página já tiver.

Formato de planos. Cada título é o nome de um plano.

• O primeiro parágrafo sob o título é o preço, renderizado em tamanho grande: **$20** / month destaca o número e mantém a unidade ao lado dele. Escreva Free ou Contact sales da mesma forma quando não houver um valor.
• O segundo parágrafo é uma linha sobre para quem o plano se destina. Ele fica entre o preço e a lista, que é a parte mais estreita do cartão.
• Uma lista se torna o que o plano inclui, com cada item marcado. Um item escrito como tachado — ~~Priority support~~ — recebe um traço e é renderizado de forma atenuada, mostrando o que um plano mais barato não inclui sem uma segunda lista.
• Um parágrafo que contenha apenas **bold text** diretamente abaixo do título se torna o selo desse plano e o marca como destaque: um anel ao redor do cartão e um botão sólido. Use-o em no máximo um plano.
• O último parágrafo composto apenas por links do plano se torna seus botões, exatamente como em cta. O primeiro botão do plano em destaque é sólido e os demais são vazados, para que o bloco tenha apenas um elemento chamativo.

Formato de matriz. A primeira coluna nomeia o recurso e todas as outras colunas são planos. Uma célula cujo texto completo seja yes, no, ✓, —, included ou none se torna uma marca ou um traço, mantendo a palavra na marcação para leitores de tela. Uma célula contendo qualquer outra coisa — 3 seats, Unlimited, uma nota de rodapé — permanece exatamente como foi escrita. Uma célula vazia continua vazia: silêncio não significa “não”.

cols=1|2|3|4 no marcador de abertura fixa a grade nesse número de colunas. O padrão acomoda tantos cartões quanto a página permitir.

Nunca escreva neste widget um preço, nome de plano, limite ou compromisso de serviço que você não tenha lido na fonte. Este é o único widget cujo conteúdo é uma promessa comercial.

Transforma seções de endpoints REST em um formulário a partir do qual o leitor pode enviar uma solicitação real, usando sua própria chave e seus próprios parâmetros.

• Um título que seja um método e um caminho — ## POST /api/v1/chat — se torna um bloco de endpoint.
• A primeira tabela sob ele com uma coluna Field (ou Name / Parameter) se torna o formulário da solicitação, com uma entrada por linha. As colunas Type, Required e Description são usadas quando presentes.
• Segmentos de caminho parametrizados, como /project/update/{projectId}, sempre recebem sua própria entrada.
• Uma entrada de autorização é sempre adicionada. A chave do leitor é enviada pelo próprio navegador dele e nunca chega ao Docsbook.
• Documentar Authorization como uma linha na tabela é aceitável: essa linha é assumida pela entrada de cabeçalho acima, mantendo sua descrição, em vez de ser renderizada novamente como um campo que colocaria a chave na URL.
• Uma subseção ### contendo um bloco de código — ### Example, ### Response — é movida para um painel de exemplos ao lado do formulário, mantendo seu título. Qualquer outra subseção, como uma tabela ### Errors, permanece no fluxo do documento abaixo.

Um pequeno bloco com borda que encerra uma página com a única ação que o leitor deve realizar em seguida.

• O primeiro título se torna o título do bloco. Ele é renderizado como uma linha estilizada, e não como um título real, portanto não aparece na estrutura da página.
• Um parágrafo inicial que contenha apenas **bold text** se torna um pequeno texto auxiliar em letras maiúsculas.
• Um parágrafo contendo apenas links se torna os botões: o primeiro é sólido e os demais têm contorno. Uma frase que apenas contenha um link continua sendo prosa.
• Use um por página e no máximo dois links. Um segundo bloco compete com o primeiro, e ambos convertem pior.

<!-- widget:cta -->
 
## Publish your docs from GitHub
 
Connect a repository and your markdown is live.
 
[Create a project](https://docsbook.io/start) · [See pricing](https://docsbook.io/pricing)
 
<!-- /widget -->

O mesmo bloco, com a ação principal apresentada como um formulário de um campo. O que o leitor digita é levado para a URL de destino, para que ele possa começar sem precisar digitá-lo novamente na página seguinte.

• A URL do primeiro link é o destino do formulário, e o texto do link identifica o botão.
• Dê um nome ao campo usando um parâmetro de consulta vazio: ?email= envia o que o leitor digitou como email. Sem uma string de consulta, o campo recebe o nome email.
• Um parâmetro que já tenha um valor é mantido inalterado — ?email=&ref=docs mantém ref=docs na URL enviada, o que é útil para atribuição.
• Defina o texto de espaço reservado com o título do link em markdown: [Join](https://example.io/signup?email= "you@company.com").
• O teclado segue o nome do campo: email abre um teclado de e-mail, e url / site / domain, um de URL.
• Um destino que não pode receber um formulário, como mailto: ou uma âncora na página, é apresentado como um botão simples.

Aponte apenas para uma URL que realmente leia o parâmetro. Uma página que o ignora descarta silenciosamente o que o leitor digitou, o que é pior do que um botão simples.

Transforma uma lista de descobertas em uma grade de cartões, cada um com um selo de gravidade e um link para agir. Use-o para descobertas concretas e priorizadas sobre sua própria documentação — resultados de auditorias, problemas de integridade do conteúdo ou qualquer lista do tipo "aqui está o que corrigir, em ordem de prioridade". Para uma lista simples de destinos, use cards.

• Cada título se torna um pequeno rótulo de grupo em letras maiúsculas acima da lista. Os títulos são opcionais — omita-os para uma única lista sem grupo.
• Cada item da lista se torna uma recomendação. - [Title](/href) — Explanation. {severity}: o texto do link é o título, e o texto após o travessão explica por que isso importa e o que fazer.
• Termine cada item com um marcador de gravidade — {urgent}, {worth-doing} ou {later}. Um item sem um marcador reconhecido é apresentado como {worth-doing}, em vez de perder sua gravidade.
• Um item sem link é apresentado como uma recomendação não clicável. Escreva um assim somente quando realmente não houver para onde encaminhar o leitor.
• Os parágrafos entre um título e sua lista são mantidos como texto introdutório comum.

<!-- widget:recommendations -->
 
- [You are paying to keep the same page twice](/docs/quickstart) — "Quickstart" and "Getting started" are 96% the same and neither links to the other. Keep one, merge the other into it. {urgent}
- [214 people found "Webhooks" the hard way](/docs/webhooks) — No page links to it, yet it still gets visits. Add a link from "Integrations". {worth-doing}
- [Nobody reads "Migration notes"](/docs/migration-notes) — Zero visits although 2 pages link to it. Reword the link text. {later}
 
<!-- /widget -->