Para quem é

Salvar documentação de API com o código inteiro

Documentação é quase toda código, e é justamente essa parte que a maioria dos clippers perde. O Clean Clipper lê a linguagem na própria página – na classe do bloco, no elemento pai ou na marcação do destacador de sintaxe – e escreve isso no bloco. Num corpus técnico de nove páginas a marca sobreviveu em 73 de 156 blocos, contra 20 e 0 dos dois motores comparados.

Onde a documentação capturada quebra

Você acha a resposta que procurava numa página de documentação, captura, cola no Obsidian e o que aparece é um paredão cinza. O bloco veio sem a marca da linguagem, então não há destaque de sintaxe. Meia hora depois, procurando aquele mesmo trecho, você não distingue onde termina o comentário e onde começa a chamada da função. O que era referência virou texto para reler inteiro.

A tabela de parâmetros é o segundo tropeço. Uma célula com null dentro, uma lista de valores aceitos, um link para outro método – e o conversor genérico desaba a linha toda numa só. Some a coluna do tipo, some a do valor padrão, e a única saída é voltar ao site, que é exatamente o que você queria não precisar fazer.

O terceiro problema é a versão. Documentação é versionada e o endereço quase nunca é: a página que você leu para a 4.x vira 6.x sem aviso nenhum, com uma opção renomeada e outra removida, e o favorito continua abrindo – só que em outro texto. Nada nas suas notas registra contra qual versão a decisão foi tomada. Um arquivo com o endereço e a data que a página trazia responde isso um ano depois; favorito nenhum responde.

O que muda na sua nota

• O bloco sai como ```js, e não pelado – o destaque funciona no Obsidian, no VS Code e no GitHub assim que você cola
• A linguagem vem da própria página: da classe do bloco, do elemento pai ou da marcação do destacador, nunca de um chute em cima do código
• Tabela de parâmetros com código, lista ou link dentro da célula não desaba mais em uma linha só
• README no GitHub, respostas do Stack Overflow e documentação de framework foram o corpus de teste original
• Em um corpus técnico de nove páginas a marca da linguagem sobreviveu em 73 de 156 blocos, contra 20 e 0 dos dois motores comparados
• Barra lateral, seletor de versão e a lista de “nesta página” ficam de fora da nota
• O campo extraction registra por onde o texto veio: dom, ou jsonld-articlebody quando a página entregou o corpo em dados estruturados e nunca o renderizou na tela
• Zero resto de tag HTML nas 512 páginas medidas – nenhum div solto sobra no meio do exemplo que você colou

A API JSON devolve dados mais ou menos assim:

```js
[
  { categoria: "Frutas", preco: "R$ 5", emEstoque: true, nome: "Maçã" },
  { categoria: "Legumes", preco: "R$ 9", emEstoque: true, nome: "Espinafre" }
]
```

## Passo 1: Divida a UI em uma hierarquia de componentes

Deixar pronto para documentação

São seis minutos uma vez só, e depois o atalho faz o resto. O padrão de fábrica é pensado para quem lê artigo; documentação pede outro nome de arquivo, nenhum campo de autor e nenhuma imagem.

1. Instale a extensão e fixe o ícone na barra do Chrome. Clique com o botão direito no ícone e escolha Opções para abrir as configurações numa aba.
2. Em o que o clique no ícone faz, escolha “salvar na pasta”. É isso que transforma a captura em uma tecla só: a janela de pré-visualização ajuda enquanto você está aprendendo a ferramenta e atrapalha depois.
3. Escolha a pasta. Aponte para um diretório que já está sob controle de versão, por exemplo docs/clips dentro do repositório em que você trabalha. O navegador pede confirmação uma vez e guarda a permissão para aquele perfil.
4. Coloque {domain}-{title} no modelo de nome de arquivo. Quatro frameworks têm uma página chamada “Primeiros passos”, e sem o domínio no nome a quarta vira primeiros-passos-4 em silêncio.
5. No bloco de frontmatter, deixe source e extraction ligados e desligue author. Documentação raramente é assinada, e um campo vazio em todo arquivo é ruído que você vai acabar tirando na mão.
6. Coloque imagens em ignorar. Captura de tela da IDE de outra pessoa não entra em busca por palavra, e o link aponta para uma CDN que vai mudar de endereço.
7. Abra chrome://extensions/shortcuts e confirme que Alt+Shift+M está livre. Se outra extensão pegou o atalho, é ali que você toma de volta.

Configuração de quem programa

Estes são os valores que vale mudar em relação ao padrão, com o motivo de cada um valer para documentação em particular, e não para leitura em geral.

Rode a migração antes de subir o servidor:

```
./bin/migrate --env producao
```

```sql
SELECT id, criado_em FROM sessoes WHERE expira_em < now();
```

O segundo bloco trazia `class="language-sql"`. O primeiro não trazia nada,
e sai pelado em vez de sair com uma marca adivinhada.

Três sessões de trabalho

Fixar a versão contra a qual você realmente construiu

Você está no ramo 4.x da documentação de um framework, lendo a página de um parâmetro de configuração que foi renomeado na 5.x. Aperta Alt+Shift+M. O arquivo cai como exemplo-dev-referencia-de-configuracao.md em docs/clips, com source apontando para o endereço /v4/ e a data que a própria página declarava no cabeçalho.

Oito meses depois o parâmetro se comporta de outro jeito em produção e ninguém lembra por que foi configurado assim. A captura está no repositório, na mesma faixa de commits da mudança, e diz contra qual versão da documentação a decisão foi tomada. O endereço no ar já serve a 6.x e nem menciona mais aquele parâmetro.

A thread que resolveu de verdade

A documentação oficial descreve o caminho feliz; a solução do seu caso está numa thread do Reddit, quatro comentários abaixo, com a resposta aceita em 140 pontos embaixo de uma errada com 30. Você captura a thread. A regra por site manda o arquivo para threads, e a estrutura dos comentários chega como citações aninhadas, cada uma com a sua pontuação.

A pontuação é justamente a parte que importa na releitura. Copiar e colar a mesma thread achata tudo e apaga esse sinal: você fica com cinco opiniões e nenhum jeito de saber em qual a comunidade concordou.

Uma tabela de variáveis direto no pull request

O guia de implantação tem uma tabela de dezoito variáveis de ambiente, três delas com um trecho de código dentro da célula. Você seleciona a tabela na página, captura a seleção e cola o Markdown na descrição do pull request. O GitHub renderiza como tabela, porque é tabela GFM, e não imagem.

No corpus técnico de quinze tabelas este serializador manteve doze, onde cada motor comparado manteve sete. As células que quebram conversor genérico são exatamente essas: as que têm código ou lista dentro.

Comparado com o jeito de hoje

Todos estes funcionam, e cada um deles é o que alguém do seu time está fazendo agora. A terceira coluna é o custo honesto – o desta extensão incluído.

Quando não sai como deveria

Por que o meu bloco de código saiu sem marca de linguagem?

Porque a página não disse qual era. O Clean Clipper lê a linguagem na classe que o destacador do próprio site deixou; ele não olha o código para adivinhar. Exemplo estilizado à mão, sem classe nenhuma, produz bloco pelado – que é o resultado honesto. Uma marca python chutada num trecho de shell é pior que marca nenhuma, porque aí o destaque colore com confiança as coisas erradas.

Por que metade do guia sumiu?

Quase sempre é aba ou sanfona. A extensão converte o que o navegador realmente renderizou, e uma aba cujo conteúdo só é inserido quando você clica não está no DOM até você clicar. Abra a aba, expanda a seção e capture – ou capture uma vez por variante. Em site que renderiza todas as abas e esconde com CSS, todas vêm, uma depois da outra.

Por que ele diz que não há artigo?

Playground de API, página de resultado de busca e índice de pacotes são quase só rótulo de link, e a extensão recusa isso de propósito: quando mais ou menos um quarto dos caracteres extraídos está dentro de link, ela avisa “não há artigo” em vez de te entregar trezentas entradas. Essa recusa é o motivo de a fatia de “texto útil” dela ficar abaixo da de motores que sempre devolvem alguma coisa.

O que quer dizer extraction: "jsonld-articlebody" no meu arquivo?

Quer dizer que a página publicou o texto do artigo nos dados estruturados e nunca terminou de renderizar aquilo no DOM, então o corpo foi lido de lá. Isso fica registrado em vez de escondido porque os dois caminhos podem divergir: às vezes a cópia dos dados estruturados é uma versão anterior, às vezes é a única completa. Quando esse valor aparecer, vale bater o olho no original antes de confiar no texto.

O que ele não faz

Ele não rastreia o site: é uma página por vez, a que está aberta na sua frente. Não baixa arquivo binário – diagrama e captura de tela continuam como links para o site original, e não como arquivos ao lado da nota. Não roda nas páginas que o navegador protege, como chrome:// e a própria loja de extensões. E não adivinha a linguagem de um bloco que a página não marcou: bloco sem marca sai sem marca, porque um chute errado é pior que campo vazio.

Perguntas