Componentes

As páginas de documentação são MDX, e esta página é o vocabulário completo de componentes: cada entrada é um componente do design system, @aziontech/webkit, ou um wrapper fino sobre um. Um componente ausente desta página não está disponível: um import dele falha o build.

Asides

Sem import. Asides são escritos como blocos ::: e renderizam o DocCallout do design system; são a construção mais comum depois dos links.

Tipos válidos: note, tip, caution, danger. caution renderiza como o tipo warning do callout.

:::warning não é válido e não renderiza como esperado. Use :::caution.

• Um callout contém prosa: frases, parágrafos curtos e uma lista. Mantenha fences e tabelas fora dele: um fence dentro de um callout renderiza cada linha em caixa, como código inline. Coloque-os antes ou depois do aside.
• O callout não tem linha de título. O texto entre colchetes é mantido como introdução à cópia (Você sabia? — ...), então use-o só quando as primeiras palavras precisarem dele. Em páginas em português, localize: :::note[nota], :::tip[dica], :::caution[Atenção].

DocButton

A call to action da casa. Um wrapper sobre o Button do design system que mantém o estilo de botão dentro do corpo do artigo.

• href e label são obrigatórios. Sem diretiva client: o botão é um link estático.
• kind: omita para a ação primária; secondary para um link de referência. outlined, text e danger também existem.
• Sempre size="medium".
• icon recebe uma classe de ícone, sempre antes do label. target="_blank" abre um destino externo em nova aba.

Code

Renderiza o CodeBlock do design system, com um botão de copiar. Blocos com fence renderizam o mesmo componente.

• Um bloco de duas ou mais linhas numera as linhas e mostra uma barra no topo com o nome da linguagem: Shell, JSON, JavaScript. Um bloco text mostra Texto.
• Um bloco de uma linha mostra o código e o botão de copiar, sem números de linha, e sem barra se não tiver um nome de arquivo.
• client:visible é obrigatório em <Code>: sem ele, o botão de copiar não funciona. Um fence já o recebe.
• Props: code, lang e duas opcionais. fileName põe um nome de arquivo na barra no lugar da linguagem. showLineNumbers substitui o padrão de numeração de linhas. Em um fence, title="index.js" depois da tag de linguagem define o nome do arquivo.

O valor é um template literal de JavaScript. Backticks e ${ dentro dele precisam de escape, e uma continuação de linha precisa de barra invertida dupla. Quando um snippet contém um dos dois, isso é motivo para usar <Code> em vez de um fence, porque você controla o escape.

Blocos com fence também são o estilo da casa. Use um fence para a saída que o leitor lê, e <Code> para a entrada que o leitor copia.

Tags de linguagem em uso: bash, sh, json, javascript, js, typescript, ts, hcl, graphql, shell, text, plaintext. Terraform é hcl, não terraform.

Tabs e Fragment

O padrão multi-interface: uma tarefa, um painel por interface. Renderiza o TabView do design system, com todos os painéis mantidos no HTML.

• client:visible é obrigatório. Sem ele, as tabs renderizam e não alternam.
• Um bloco pareia cada tab.x com um panel.x. A única exceção é o seletor de interface de uma página de Quickstart: um bloco no topo com apenas slots tab.x, depois blocos da mesma sharedStore com apenas slots panel.x.
• Linhas em branco ao redor de markdown dentro de um Fragment são obrigatórias, ou o markdown renderiza como um único parágrafo literal.
• A primeira tab é o padrão, e os painéis são pareados com as tabs pela chave; coloque o Console primeiro, a menos que exista um motivo para não fazer isso.
• Chaves canônicas: tab.console, tab.api, tab.cli, mais tab.apiv3 / tab.apiv4 para APIs versionadas. Uma chave tem apenas letras minúsculas e dígitos: um hífen escapa da checagem de pareamento tab.x / panel.x sem falhar nela.
• O sharedStore="<chave>" opcional sincroniza a seleção entre grupos de tabs de uma página. Tabs de interface usam sharedStore="interface", então uma seleção acompanha o leitor em uma página que repete as tabs por seção, e também até a página seguinte: essa única store é guardada no navegador e escrita na URL como #interface=<chave>. Dê a todo bloco que compartilha uma chave as mesmas tabs. Um bloco que não oferece a chave selecionada abre no próprio primeiro painel, e deixa a seleção intacta para os blocos que a oferecem.

Tag

Selos de status.

• Sem diretiva client: o selo é HTML estático.
• severity é success, info, warning ou danger. info é o chip neutro de rótulo, usado para “Preview” e selos de produto; os outros três são cores de status.
• O label vai nos filhos. value="Preview" também é aceito.

Video

Sem import. Emite o iframe mais os metadados VideoObject do schema.org.

src precisa ser uma URL de embed do YouTube. src e title são obrigatórios. Para uma captura de tela ou um arquivo de clipe, use Figura.

Diagramas Mermaid

Um diagrama é um fence de código mermaid, não uma imagem. O texto chega a um agente que busca o twin em markdown; uma referência de imagem, não.

title="..." depois de mermaid no fence adiciona uma legenda abaixo do diagrama. Nomeie cada nó e cada aresta em palavras, e nunca dependa de cor sozinha para carregar uma distinção. Um diagrama nunca fica sozinho: páginas de arquitetura e de caso de uso mantêm o fluxo de dados numerado abaixo dele.

Passos

Um passo a passo numerado: cada passo é um título com um corpo opcional, e os números vêm da ordem na página.

• Sem diretiva client.
• Nunca escreva o número: reordenar os passos os renumera.
• Um DocStep fica sempre dentro de um DocSteps. Linhas em branco ao redor do markdown dentro de um passo são obrigatórias.

Figura

Uma captura de tela, um clipe ou um diagrama emoldurado, com uma introdução opcional acima e uma legenda abaixo.

• src recebe uma imagem ou um clipe (.mp4, .webm). Dê um alt a uma imagem. Sem src, a moldura envolve os filhos, como um fence mermaid.
• caption e hint são strings simples; os slots de mesmo nome (<Fragment slot="caption">) carregam uma legenda com link ou código inline.
• autoplay reproduz um clipe sem som, inline e em loop, sem controles.

Cards

Uma grade de cards de navegação, para uma página que se abre em seções. É a seção ## Próximos passos que fecha uma página: um card por destino, com o motivo como texto.

• Sem diretiva client.
• cols é 2, 3 ou 4; a grade colapsa para uma coluna no celular.
• href transforma o card inteiro em link. label é a cópia; os filhos a substituem quando a cópia precisa de um link ou de código inline.
• Opcionais: icon recebe uma classe PrimeIcons (pi pi-bolt), overline uma linha pequena acima do título, link um texto de call to action em uma linha de fechamento.

Itens relacionados

Uma lista emoldurada de linhas, cada uma com um nome e uma frase, para um leitor escolhendo o que ler em seguida. É a seção ## Relacionados que fecha uma página.

• Sem diretiva client. FrameBox desenha o perímetro; ItemList traça as linhas entre os itens.
• href transforma a linha em link; uma URL externa recebe a seta para fora. O icon opcional recebe uma classe PrimeIcons.
• A cópia é uma frase: o que a coisa é, ou por que o leitor iria até lá. Código inline e links são permitidos; blocos, não.

Entrada de changelog

Uma entrada datada: rótulo e versão à esquerda, as notas à direita, com uma âncora derivada do rótulo.

• Sem diretiva client. Linhas em branco ao redor do markdown interno são obrigatórias.
• label é a âncora, em slug. Duas entradas com o mesmo rótulo precisam de valores distintos de anchor.
• description é a linha abaixo do rótulo; tags é um array de rótulos curtos.
• Uma página de entradas tem o sumário montado a partir delas: o painel da direita lista uma linha por data e aponta para a primeira entrada daquela data, no lugar dos headings dentro das notas. O padrão de Changelog tem o resto.

Prompt

Um bloco de texto literal que o leitor entrega a um agente, em fonte mono e com um controle de copiar. Não é um bloco de código: sem linguagem, sem highlighting.

• client:visible é obrigatório: o controle de copiar e o de expandir precisam dele.
• kind="line" faz uma única linha com rolagem em vez de um parágrafo limitado a quatro linhas. title e icon são opcionais.

Glosa inline

Um termo no meio da prosa que mostra sua definição ao passar o mouse ou receber foco, com um link opcional.

• client:visible é obrigatório; sem ele o termo renderiza e nunca abre.
• tip é a definição, headline a introdução em negrito, cta mais href o link.

Fornecidos pelo layout

DocPageHeader (a partir de title e description no frontmatter), DocOnThisPage, DocPagination e o contrato tipográfico DocProse renderizam ao redor de toda página. Nunca os escreva.

Snippets compartilhados

Blocos reutilizáveis em ~/includes/snippets/, cada um com uma variante en/ e uma pt/. Note que a pasta do português é pt/, não pt-br/.

Disponíveis: apiv4Rollout, JourneyAPI, InterfaceNote, LetsEncryptExpiration, RulesEngineExecution.

SectionBasicContent

O bloco de cabeçalho de uma página de vitrine de template. Importe de ~/components/webkit/SectionBasicContent.vue. Recebe description e um array buttons, com o resto da página em um <Fragment slot="content">. Cada botão recebe label, link e, opcionalmente, severity: "secondary", outlined: true, icon e target. Um botão sem link não renderiza nada. Leia uma página de vitrine existente antes de usar.

ProductGuidesSection

Renderiza o hub de Guias e tutoriais como uma tabela de nome, tipo e última atualização. Usado na página de hub de uma seção de produto, e em nenhum outro lugar.

• product — o id da seção, como applications. A tabela lista todo guia que o catálogo de guias marca com a seção ou com um produto aninhado nela.
• A data é a da última alteração da página, preenchida automaticamente. Nunca escreva a data à mão.
• A coluna de tipo mostra o tipo de conteúdo de cada página, no idioma do leitor.
• As linhas ordenam por título.

GlossaryFilter

Filtro client-side sobre uma tabela de glossário. Usado na página de Glossário de um produto, e em nenhum outro lugar.

• O filho é uma tabela pipe de GFM, | Termo | Definição |. Linhas em branco ao redor dela são obrigatórias.
• lang localiza o placeholder do filtro e a mensagem de estado vazio: en ou pt-br.
• Cada linha do corpo recebe uma âncora derivada do termo, com ASCII-folding (ação múltipla → #acao-multipla), então uma definição aceita deep link. As âncoras existem sem JavaScript.
• O filtro é um aprimoramento progressivo: sem JavaScript, a tabela inteira renderiza. A correspondência ignora maiúsculas e acentos, sobre a linha inteira.

Tabelas e quebras de linha

Tabelas são pipe tables de GFM simples. A rolagem horizontal é adicionada automaticamente; não as envolva você mesmo.

<br /> ou <br></br>. Um <br> sem fechamento quebra o build — MDX exige toda tag fechada.

Regras de MDX que quebram builds

• < e { soltos na prosa são interpretados como JSX. Escape-os ou use backticks.
• Toda tag precisa estar fechada ou ser autofechada.
• Nenhum H1 no corpo; o title o renderiza.
• --- entre seções principais é o estilo da casa, cerca de três por página. Nunca imediatamente depois do bloco de frontmatter.
• Os imports vêm logo depois do bloco de frontmatter, antes de qualquer prosa.

Recursos relacionados