Documentação para Consumo por IA

Configuração do plugin Antora Assembler com a extensão HTML Single para gerar, além do portal HTML navegável, uma versão consolidada da documentação em formato amigável para consumo por inteligências artificiais (LLMs).

Motivação

O portal de documentação gerado pelo Antora é otimizado para navegação humana: páginas individuais com sidebar, breadcrumbs, busca, etc. Para consumo por uma IA, esse formato é ineficiente — a IA precisa de documentos consolidados, limpos e sem crosta de navegação.

A extensão @antora/html-single-extension resolve isso ao:

  • Consolidar todas as páginas de cada componente/versão em um único documento HTML standalone

  • Produzir HTML limpo, sem navegação, sidebar ou UI do portal

  • Manter opcionalmente o AsciiDoc montado (assembly) para uso como contexto textual puro

Visão geral

assembler-overview

Arquivos envolvidos

Arquivo Finalidade

package.json

Centraliza todas as dependências npm (Antora, extensões, kroki) e define overrides para forçar versões compatíveis do @asciidoctor/core.

antora-playbook.yml

Registra a extensão @antora/html-single-extension na lista de extensões do Antora.

antora-assembler-html.yml

Configuração do Assembler para o formato HTML Single (filtro de componentes, build, atributos).

Dockerfile

Build multi-stage usando node:22.15.0-alpine com npm install a partir do package.json.

.gitlab-ci.yml

Pipeline CI usando a mesma imagem e estratégia de instalação.

Configuração do Assembler

O arquivo antora-assembler-html.yml na raiz do projeto controla o comportamento da extensão:

component_version_filter:
  names: '**'          (1)
assembly:
  attributes:
    source-highlighter: highlight.js
build:
  command: false       (2)
  keep_source: true    (3)
  qualify_exports: true (4)
1 Gera saída para todos os componentes e versões (fuji, artes-marciais-online, etc.)
2 Usa o Asciidoctor.js embutido no Antora — não requer Ruby instalado
3 Preserva os arquivos .adoc montados (assembly) em build/assembler-html/, excelentes para dar como contexto a um LLM
4 Qualifica os nomes dos exports com componente e versão (ex: fuji-main.html)

Registro no playbook

A extensão é registrada em antora-playbook.yml:

antora:
  extensions:
    - require: '@antora/lunr-extension'
      languages: [pt]
    - require: '@antora/html-single-extension'

Resolução de dependências

O problema com Node.js 22 e o Opal Runtime

O Antora Assembler exige Node.js 22.15.0+. Porém, a imagem oficial antora/antora usa Node 18 e não existe versão oficial com Node 22.

Ao migrar para node:22-alpine, o @asciidoctor/opal-runtime@3.x (dependência transitiva do @asciidoctor/core@3.x) causa o erro:

Opal.queue is not a function

Isso acontece porque o runtime Opal 3.x é incompatível com mudanças no V8 do Node.js 22.

A solução: package.json com overrides

{
  "private": true,
  "dependencies": {
    "@antora/cli": "3.2.0-alpha.11",
    "@antora/site-generator": "3.2.0-alpha.11",
    "@antora/html-single-extension": "1.0.0-beta.19",
    "@antora/lunr-extension": "1.0.0-alpha.10",
    "asciidoctor-kroki": "0.18.1"
  },
  "overrides": {
    "@asciidoctor/core": "~2.2",
    "@asciidoctor/opal-runtime": "npm:asciidoctor-opal-runtime@0.3.3"
  }
}

Os overrides do npm garantem que:

  • @asciidoctor/core é sempre resolvido para a linha 2.2.x (compatível com Antora)

  • @asciidoctor/opal-runtime (scoped, 3.x) é redirecionado para asciidoctor-opal-runtime@0.3.3 (unscoped, compatível com Node 22)

Imagem Docker

A imagem base foi trocada de antora/antora:3.2.0-alpha.x para node:22.15.0-alpine:

FROM node:22.15.0-alpine as antora
RUN apk add --no-cache git
COPY . /work
WORKDIR /work
RUN npm install
RUN npx antora generate --stacktrace --fetch --clean antora-playbook.yml
O Node está pinado em 22.15.0 (versão mínima exigida pelo Assembler) para evitar regressões com patches futuros.

Saída gerada

Após o build, os seguintes artefatos ficam disponíveis:

Artefato Localização Uso

Portal HTML navegável

build/site/

Navegação humana (publicado no nginx)

HTML Single (standalone)

build/site/<componente>/<versão>/

Documento consolidado para IA — um .html por componente

AsciiDoc Assembly

build/assembler-html/

Texto puro .adoc — ideal como contexto para LLMs

Referências