Anexos da Documentação

Anexe imagens e arquivos diretamente a qualquer página de documentação. Solte uma captura de tela no editor e ela é incorporada no texto; anexe um PDF, uma especificação ou um arquivo compactado e ele aparece como um cartão para download. Os arquivos ficam em object storage — sem nunca inchar o seu banco de dados — e acompanham a página onde quer que ela seja visualizada ou compartilhada.

Adicionando Anexos

Abra uma página de documentação no editor (Novo documento ou Editar) e adicione arquivos da forma que for mais rápida:

  • Arraste e solte um ou mais arquivos sobre o editor
  • Cole uma imagem direto da área de transferência (por exemplo, uma captura de tela)
  • Clique em Anexar arquivo na barra de ferramentas do editor e escolha os arquivos

Você pode anexar vários arquivos de uma vez. Um documento novo é salvo automaticamente na primeira vez que você anexa um arquivo, para que nenhum envio se perca.

Imagens vs. arquivos

O Archyl trata os dois casos como você espera:

  • Imagens são incorporadas no texto do seu Markdown, no ponto em que você as adiciona, e aparecem diretamente na página.
  • Outros arquivos (PDFs, documentos, arquivos compactados…) são adicionados ao painel Anexos como cartões para download, em vez de serem inseridos no texto.

Visualizando Anexos

Durante a leitura de uma página, os anexos aparecem em um painel Anexos no topo do documento, logo abaixo do título — assim os leitores veem o que está disponível antes de rolar a página. Cada arquivo mostra:

  • Um ícone por tipo, com código de cores, ou uma miniatura da imagem
  • O nome, o tipo e o tamanho do arquivo
  • Uma ação de download com um clique

As imagens também aparecem no texto, onde quer que você as tenha colocado no conteúdo.

Gerenciando Anexos

No editor, o painel Anexos permite:

  • Baixar qualquer arquivo
  • Excluir um arquivo (com uma confirmação rápida no próprio painel) — isso também o remove do armazenamento

Excluir um documento também remove os seus anexos.

Arquivos Suportados

Você pode anexar qualquer tipo de arquivo. As imagens são incorporadas no texto; todo o resto aparece como um cartão para download. Exemplos comuns:

  • Imagens — PNG, JPEG, GIF, WebP, SVG, AVIF
  • Documentos — PDF, Word, Excel, PowerPoint, texto simples, Markdown, CSV
  • Dados e arquivos compactados — JSON, YAML, ZIP, logs

O tamanho máximo padrão é de 10 MB por arquivo (configurável em instâncias self-hosted).

Dica: se o seu navegador não reconhecer um tipo de arquivo, ele ainda assim é aceito e oferecido para download.

Armazenamento e Privacidade

Os anexos ficam em object storage, e não no banco de dados da aplicação. No Archyl Cloud, esse armazenamento é o Google Cloud Storage — gerenciado para você, sem nada para configurar. Em instâncias self-hosted, você escolhe o seu próprio provedor compatível com S3 (veja abaixo).

Em ambos os casos:

  • O bucket é privado. Os arquivos são servidos por links assinados de curta duração, gerados sob demanda — os objetos subjacentes nunca podem ser listados publicamente.
  • Os links incorporados em uma página permanecem estáveis, então a documentação compartilhada e pública continua funcionando sem expor o bucket.
  • A criptografia em repouso vem ativada por padrão. O Google Cloud Storage criptografa cada objeto automaticamente; em instâncias self-hosted, você também pode fornecer as suas próprias chaves (por exemplo, uma CMEK do Cloud KMS no GCS).

Para Instâncias Self-Hosted

No Archyl Cloud, os anexos funcionam sem nenhuma configuração. Se você usa self-hosting, precisa trazer o seu próprio object storage — e pode apontar o Archyl para qualquer provedor compatível com S3 (Google Cloud Storage, Amazon S3, MinIO, Cloudflare R2…).

Enquanto o armazenamento não estiver configurado, a ação Anexar arquivo fica indisponível e os envios retornam uma mensagem clara "File storage is not configured". Defina as variáveis de ambiente STORAGE_* no backend (endpoint, bucket, chave de acesso, chave secreta) para ativar o recurso; para o Google Cloud Storage, use o endpoint de interoperabilidade (HMAC). Consulte a configuração da sua implantação para ver a lista completa de opções.

Próximos Passos