Padrão de documentação HTML

Este é o documento exemplo do padrão: um arquivo HTML único, legível e navegável, criado por agentes de IA e editado inline no Remote OS. Ele documenta o próprio padrão — cada elemento exibido aqui é também a referência de como usá-lo. Em qualquer navegador o arquivo é só leitura, com tudo funcionando; a edição pertence ao Remote OS e é o próprio documento que a autoriza, pela meta doc-format.

Visão geral

Cada documentação é um arquivo .html que guarda só o conteúdo: a apresentação vem de html-docs.tiagofischer.com, que serve o estilo, o script, as fontes, o realce de código e os diagramas. Princípios do padrão:

Semântico — o conteúdo usa apenas HTML padrão (h1–h4, p, listas, tabelas…) e um conjunto pequeno de classes utilitárias.
Enxuto — sem CSS nem JS embutidos, um documento cabe em uma fração dos tokens que custava. É o que permite a um agente de IA ler muitos documentos numa sessão.
Editável por opção — o texto pode ser ajustado inline no Remote OS sem quebrar o arquivo, e é o arquivo que declara essa permissão; ver Contrato de edição.
Resiliente — sem rede, o fallback do <head> mantém o documento legível: fontes do sistema, coluna de leitura, código monocromático e a fonte textual dos diagramas.
Automático — sumário lateral (opcional, ver Índice opcional), âncoras, realce de código e diagramas são gerados pelo script servido; o autor escreve só o conteúdo.

O que o documento carrega

Três linhas no <head>, e são as mesmas em todo documento do padrão:

<style>@layer fallback{ /* legibilidade mínima sem rede */ }</style>
<link rel="stylesheet" href="https://html-docs.tiagofischer.com/doc.css">
<script defer src="https://html-docs.tiagofischer.com/doc.js"></script>

O fallback fica em @layer de propósito: regra em layer perde para regra fora de layer, então o doc.css vence sempre que declara a mesma propriedade — sem depender de especificidade nem de ordem. A contrapartida é que o que o fallback declara e o doc.css não redeclara continua valendo; por isso o fallback se limita a propriedades que a folha servida também define.

Nota: as URLs não têm versão. Mexer no doc.css muda todo o acervo de uma vez — o histórico fica no git do projeto html-docs. Uma quebra incompatível nasceria como /v2/doc.css, junto com doc-format: html-docs/2.

Estender o padrão

A liberdade continua a mesma: um documento pode redefinir tokens, criar componentes e trazer comportamento novo. Muda só onde isso entra.

CSS — um <style> próprio depois do <link>. Por estar fora de qualquer layer, vence o doc.css.
JS — um <script> próprio que escuta htmldoc:ready no document. O doc.js é defer e roda depois dos scripts inline do documento, então window.htmlDoc ainda não existe quando eles executam. O evento sai quando o documento está pronto de verdade: sumário montado, blocos de código realçados e diagramas desenhados — dá para mexer no Shadow DOM de qualquer um deles sem esperar por conta própria.

<script>
document.addEventListener('htmldoc:ready', () => {
  // window.htmlDoc já existe aqui
});
</script>

Estrutura

Todo documento mantém a mesma shell: uma sidebar fixa com o sumário (gerado automaticamente) e a área de conteúdo #doc. O esqueleto:

<body>
  <div class="layout">  <!-- grid: sidebar à esquerda, conteúdo à direita -->
    <main><div class="doc-wrap">
      <article id="doc">
        <h1>Título</h1>
        <p class="lede">Abertura…</p>
        <h2 id="section-id">Seção</h2>
        …
      </article>
    </div></main>
    <nav class="sidenav">
      <p class="brand">…</p>
      <p class="doc-meta">…</p>
      <div id="toc-host"></div>  <!-- sumário automático -->
    </nav>
  </div>
</body>

Regras da estrutura:

O <main> vem antes da .sidenav no DOM; o grid do .layout reposiciona a sidebar à esquerda. Assim o documento começa no conteúdo — a ordem de leitura, a tabulação e o Ctrl+Home caem no h1 do artigo, não na moldura.
O h1 é único e vem seguido de um parágrafo .lede de abertura.
h2 e h3 entram no sumário lateral e devem ter IDs explícitos (kebab-case, em inglês) para links estáveis — ex.: id="partial-file". Quem ficar sem ID recebe um automático, derivado do próprio texto; ele acompanha o título enquanto está sendo editado e vira definitivo ao salvar. IDs já presentes no arquivo nunca são reescritos.
h4 é o nível máximo de aprofundamento; não entra no sumário.
O <head> declara o formato do documento na meta doc-format — ver Contrato de edição.

Índice opcional

Nem todo documento precisa de sumário: uma nota, um registro curto ou uma lista de tarefas ficam melhores sem a moldura lateral. A exibição é uma propriedade do próprio arquivo, declarada no <head>:

<meta name="doc-toc" content="on">   <!-- padrão: sidebar com o sumário -->
<meta name="doc-toc" content="off">  <!-- coluna única, conteúdo centralizado -->

Com off some a sidebar inteira — marca, meta e sumário — junto do botão ☰ das telas estreitas. O conteúdo passa a ocupar uma coluna única centralizada; as âncoras #id continuam funcionando.
A ausência da meta equivale a on: documentos anteriores a esta opção seguem inalterados.
A .sidenav permanece no arquivo em ambos os casos — alternar é trocar uma palavra, não reescrever a estrutura.
Trocar a palavra é a única edição necessária: a sidebar continua no arquivo, e o layout reage à meta por CSS — sem script e sem recarregar.

Elementos

Catálogo dos elementos do padrão — cada exemplo abaixo é a própria referência visual.

Tipografia

Texto corrido com negrito para o essencial, ênfase para nuances, links internos por ID e termos técnicos como tb_arquivo em código inline. Atalhos de teclado usam kbd: salve com Ctrl+S.

Título de quarto nível

Usado para subdivisões pontuais dentro de um h3 — como os itens numerados de uma análise. Um hr separa blocos sem criar seção:

Texto após a quebra temática.

Anotações e revisão

Ao lado de strong, em, code e kbd, o padrão veste a semântica inline que registra mudança e contexto. Nenhuma delas precisa de classe — é HTML nativo:

mark — trecho destacado para o leitor voltar depois; é realce de leitura, não ênfase do autor (essa é do strong).
ins / del — o que entrou e o que ~~saiu~~ numa revisão, com o texto anterior ainda visível.
abbr — sigla com o significado no title: PWA, CSS.
time — data legível por máquina no atributo datetime e formatada no texto: revisado em 17/08/2026.

Nota: ins e del marcam uma revisão dentro do texto, não histórico de versões — para "o que mudou no arquivo" o lugar é o git. Servem quando a decisão anterior importa para quem lê.

Notas de rodapé

Aparte que interromperia a frase — uma referência, uma ressalva de escopo, o número de um ticket — sai do parágrafo e vira nota ao fim do artigo. A chamada é um sup com link; a lista é uma ol.footnotes, o último elemento do #doc¹:

<p>O realce roda em Shadow DOM<sup id="fnref-1"><a href="#fn-1">1</a></sup>.</p>

<!-- ao fim do <article id="doc"> -->
<ol class="footnotes">
  <li id="fn-1">Texto da nota. <a class="backref" href="#fnref-1" aria-label="voltar ao texto">↩</a></li>
</ol>

IDs em par: fn-N na nota e fnref-N na chamada, numerados na ordem de aparição.
Ida e volta são âncoras comuns; ao chegar pela chamada, a nota se destaca sozinha por :target. Nada é gerado — o número visível vem da própria ol.
Renumerar é trabalho manual, o que é um argumento a favor de poucas notas: só o que realmente não cabe no texto.

Listas

Listas não ordenadas para enumerações, ordenadas para sequências/procedimentos. Aninhamento livre:

Item com detalhes:
- subitem de apoio;
- outro subitem.
Item simples.

Primeiro passo do procedimento.
Segundo passo, com resultado esperado.

Listas de definição

Termo e explicação — glossário, parâmetros de uma chamada, campos de um registro — vão em dl, com dt para o termo e dd para a definição. É o formato certo quando a alternativa seria uma tabela de duas colunas ou uma lista de strong seguido de travessão:

doc-format: Formato que o arquivo declara seguir. Sem a meta, o Remote OS abre o documento só para leitura.
doc-toc: on (padrão) mostra a sidebar com o sumário; off deixa o conteúdo em coluna única.
--measure: Largura máxima da coluna de leitura.; Um documento pode reduzi-la no seu próprio <style> para um texto mais estreito.

Um dt aceita vários dd — como --measure acima, com a definição e a observação separadas.
dt e dd são blocos de texto do contrato de edição: editáveis inline como qualquer parágrafo.
Sem classe alguma — a semântica é do HTML, e a lista serve tanto a um glossário quanto a uma ficha de metadados.

Código

Blocos de código ficam em <div class="code"><pre><code class="language-x">. O wrapper .code ativa o realce de sintaxe e o botão copiar; a classe language-* define a linguagem (sem ela, o realce é automático).

-- Arquivos carregados na última semana
SELECT f.nrarquivo, f.nmarquivo, s.descricao
  FROM tb_arquivo f
  JOIN tb_situacao s ON s.id = f.idsituacao
 WHERE f.dtcarga >= CURRENT_DATE - INTERVAL '7 days'
 ORDER BY f.dtcarga DESC;

# Disparo manual do job em dev
curl -s "http://localhost:8100/api/v1/run-job/5?force=true"

Nota: a fonte do bloco permanece intacta no HTML — o realce é renderizado à parte, em Shadow DOM, e nunca é gravado. O <pre> começa na coluna 0: qualquer indentação dele viraria conteúdo do código.

Callouts

Callouts são blockquote. O padrão (âmbar) marca notas e observações; as variantes .warn e .ok marcam atenção e resolução:

Nota: observação relevante que complementa o texto sem interrompê-lo.

Atenção: comportamento inesperado, pendência ou risco que o leitor precisa conhecer.

Resolvido: item verificado, testado ou concluído — com a evidência correspondente.

Tabelas

Tabelas sempre embrulhadas em <div class="tbl"> (garante rolagem horizontal em telas estreitas). A tabela abaixo também serve de referência: são as classes utilitárias do padrão — um documento pode acrescentar as suas, sobretudo spans customizados.

Classe	Aplica-se a	Uso
`.lede`	`p` após o `h1`	Parágrafo de abertura do documento.
`.code`	`div` em volta de `pre > code`	Realce de sintaxe + botão copiar.
`.tbl`	`div` em volta de `table`	Rolagem horizontal e moldura.
`.warn` / `.ok`	`blockquote` ou `.tag`	Variantes de atenção / resolvido.
`.tag`	`span`	Badge de status inline (span customizado).
`.path`	`span`	Caminho de arquivo/diretório (span customizado).
`.footnotes` / `.backref`	`ol` ao fim do `#doc` / `a`	Notas de rodapé e link de volta à chamada.
`.mermaid-host` / `.mermaid-src`	`div` / `pre`	Diagrama Mermaid (fonte + renderização).
`.mono`	`span`, `p`	Fonte monoespaçada sem caixa de código.

Conteúdo recolhível

Detalhes longos que não devem pesar na leitura principal (logs, listas extensas, evidências) vão em details:

Evidência completa do teste CT-001

Conteúdo que só aparece quando expandido — pode conter parágrafos, listas e código.

Entrada: arquivo EXEMPLO.PROC;
Saída: retorno 0000, situação SUCESSO.

Diagramas

Fluxos e sequências usam Mermaid. A fonte do diagrama fica no HTML (dentro de .mermaid-src) e é renderizada em SVG ao abrir a página — sem rede, a fonte textual permanece visível:

flowchart LR
  draft[Rascunho] --> review{Revisão}
  review -->|ajustes| draft
  review -->|ok| published[Publicado]
  published --> maintenance[Manutenção contínua]

Spans

Quando um trecho dentro de um parágrafo precisa de aparência ou semântica própria — e nenhuma tag semântica serve (strong, em, code, kbd) — ele vira um span customizado: <span class="nome"> mais uma regra CSS num <style> do próprio arquivo, depois do <link> (ver Estender o padrão). É o ponto de extensão inline do padrão; o repertório é do documento, não do padrão.

Este arquivo define dois:

.tag — badge de status pontual: achado para descobertas, testado para itens verificados e pendente para o que ainda falta (variantes .ok e .warn, combinadas como class="tag ok").
.path — caminho de arquivo ou diretório, como packages/frontend/app/components ou DOC.html: mono discreto, sem a caixa de code, que fica reservada a identificadores e trechos de código.

Ou seja: badge não é um recurso à parte — é apenas um span customizado cuja classe (.tag) foi estilizada como etiqueta. .path é outro, com a mesma mecânica e aparência completamente diferente.

Criando um span customizado

Três passos, sem tocar em nada fora do arquivo:

<!-- 1. regra no <style> do documento, sempre escopada em #doc -->
<style>
#doc .env{
  font-family:var(--font-mono); font-size:.82em; letter-spacing:.04em;
  color:var(--ok); border:1px dashed rgba(133,185,143,.45);
  border-radius:5px; padding:.05em .45em;
}
</style>

<!-- 2. uso no conteúdo, dentro de um bloco de texto -->
<p>Aplicado em <span class="env">produção</span> na última janela.</p>

O terceiro passo é só nomear bem: classe em inglês, curta, descrevendo o papel do trecho (env, path, tag) e não a aparência (green, small). Variantes seguem o padrão do .tag: uma classe base mais um modificador (class="env staging"), o que mantém o CSS enxuto.

O repertório de spans de um documento é descoberto do próprio conteúdo — uma classe só existe, para quem edita, depois de ser usada ao menos uma vez dentro de #doc. Definir a regra no <style> é metade do trabalho; a outra metade é usá-la.

Nota: o span marca um trecho dentro de um bloco de texto. Ele não serve como recipiente de texto solto (fora de p, li, td…) — ver Contrato de edição.

Contrato de edição

O arquivo declara no <head> qual formato ele segue — e é isso que o autoriza a ser editado inline:

<meta name="doc-format" content="html-docs/1">

Sem essa meta — ou com uma versão que o editor ainda não conheça — o documento abre só em visualização, exatamente como num navegador. Num navegador a meta é inerte: apenas um dado no <head>. O portão existe porque só um documento que segue as convenções daqui sobrevive ao ciclo de abrir, editar e salvar; declará-la é afirmar quatro coisas:

Texto de bloco vive em blocos de texto — p, h1–h6, li, blockquote, td/th, dt/dd, summary, figcaption, caption. Texto solto em div ou span pode ser silenciosamente perdido ao salvar. Um callout é <blockquote><p>…</p></blockquote>, nunca texto direto no blockquote.
Nada gerado entra no conteúdo — sumário, realce e diagramas vão para Shadow DOM, que não é serializado. Um script que mutasse o DOM de #doc teria a mutação gravada no arquivo.
Scripts se abstêm quando o editor assume — o editor marca o <html> com data-ros-editing, e é o documento que consulta a marca e se afasta: é assim que o bloco de código deixa de ser renderizado read-only para poder ser editado.
O arquivo em disco sai limpo — os marcadores de runtime (data-ros-*) nunca são escritos no fonte nem sobrevivem ao save².

Um documento que precise se afastar dessas convenções tem uma saída limpa: não declarar a meta e viver como documento de leitura, em vez de arriscar perder conteúdo ao salvar.

A chamada usa line-height:0 no sup, para o número não abrir a entrelinha do parágrafo — detalhe do doc.css, não do conteúdo. ↩
O prefixo ros- vem de Remote OS: o nome é do editor, e o padrão promete apenas que nenhum atributo assim chega ao disco. ↩