Para quem é
Documentação em Markdown sem faxina depois
Migrar documentação costuma ser converter o HTML e depois gastar mais tempo tirando o que o conversor manteve. Essa remoção é justamente para o que o Clean Clipper foi feito, e é a parte que está medida: zero resto de tag HTML nas 512 páginas do corpus, em doze idiomas.
A conversão que dá mais trabalho depois
Você converte cinquenta páginas da documentação antiga e recebe cinquenta arquivos com o índice lateral inteiro no topo, o seletor de versão no meio e um div solto onde havia um aviso. Cada arquivo pede dez minutos de limpeza manual. A conversão levou um minuto e a faxina leva a semana, e é a parte que ninguém coloca na estimativa.
Os detalhes que definem qualidade são os primeiros a cair. O bloco de código perde a marca da linguagem e o destaque some do site novo. A caixa de aviso vira parágrafo sem distinção nenhuma. A tabela de parâmetros quebra na célula que tinha uma lista. No fim, alguém revisa página por página comparando com o original, que era o trabalho que a conversão prometia evitar.
E existe a pergunta que ninguém faz antes de começar: quantas daquelas páginas ainda valem alguma coisa. Um site de documentação com quatrocentas páginas costuma ter noventa em uso, cem obsoletas e o resto duplicado em versões antigas. Conversão em massa move as quatrocentas, e o site novo nasce com o mesmo entulho e mais o trabalho de revisar tudo. Migrar página a página é mais lento na primeira semana e mais rápido no mês, porque a seleção acontece junto com a conversão.
O que muda na migração
- Títulos, listas, tabelas, blocos de código e notas de rodapé viram Markdown padrão
- A marca de linguagem é preservada nos blocos de código: 73 de 156 no corpus técnico, contra 20 e 0
- Zero resto de tag HTML nas 512 páginas medidas, em doze idiomas
- Barra lateral de navegação e seletor de versão são cortados, e não convertidos em lista
- Caixa de aviso e destaque viram citação em bloco – o conteúdo fica, o estilo não
- Modelo de nome de arquivo e subpasta mantêm um conjunto importado organizado desde a primeira página
- A extração roda sobre o DOM já renderizado, então wiki interna atrás de SSO converte igual a uma página pública
- Links de referência viram notas
[^1]com as definições no fim do arquivo, e não âncoras apontando para um#refque não existe mais
## 4.4. Instruções break e continue, e cláusulas else em laços A instrução break interrompe o laço for ou while mais interno. > Nota > A cláusula else pertence ao laço for, e não à instrução if.
Preparar uma migração
A configuração leva dez minutos e decide como o conjunto migrado vai ficar organizado. Vale fazer antes da primeira página, porque renomear duzentos arquivos depois é outro projeto.
- Instale a extensão e abra as opções pelo botão direito no ícone. Confirme o atalho em
chrome://extensions/shortcuts: numa migração você vai usá-lo centenas de vezes. - Aponte a pasta de destino para o diretório de conteúdo do novo site, na estrutura que o gerador espera. Assim a captura já nasce no lugar, e não numa pasta intermediária que alguém vai ter que mover.
- Use o campo de subpasta para espelhar a seção da documentação que você está migrando naquele momento. Uma seção por vez mantém a revisão possível e o progresso visível.
- Coloque
{title}no modelo de nome quando o gerador monta o endereço a partir do nome do arquivo, ou{domain}-{title}quando você está trazendo material de mais de uma origem. - Ligue
title,sourceeextractionno frontmatter e desligueauthor. Osourceé o que permite conferir a página original durante a revisão, e some do publicado se o seu gerador não usar o campo. - Em o que o clique no ícone faz, escolha “salvar na pasta” depois de validar as dez primeiras páginas na janela de captura. Antes disso, veja cada resultado: é nessa amostra que você descobre o padrão de sujeira daquele site.
Ajustes para migrar documentação
Estes valores partem de uma migração real: dezenas ou centenas de páginas, feitas por uma pessoa, revisadas por outra, com prazo definido antes de alguém saber o tamanho do problema.
| Configuração | Valor | Por que esse valor aqui |
|---|---|---|
| Pasta | O diretório de conteúdo do novo site | A captura nasce no lugar certo, sem etapa intermediária de mover arquivos |
| Subpasta | Espelha a seção que está sendo migrada | Uma seção por vez mantém a revisão possível e o progresso visível |
| Modelo de nome | `{title}`, ou `{domain}-{title}` com várias origens | O gerador costuma montar o endereço a partir do nome do arquivo |
| Frontmatter | `title`, `source`, `extraction` ligados; `author` desligado | `source` permite conferir a página original durante a revisão |
| Imagens | Manter como link | O link registra qual figura era; a migração das imagens é um projeto à parte |
| Clique no ícone | Salvar na pasta, depois das dez primeiras | As dez primeiras na janela mostram o padrão de sujeira daquele site |
## Instalação ```bash pip install exemplo ``` Consulte a [referência de configuração](https://docs.exemplo.com.br/config) antes de subir em produção. > Nota > A instalação em ambiente isolado é recomendada. A aba "conda" não veio: o navegador só insere o conteúdo dela quando você clica. E o link continua apontando para o site de origem – a reescrita para os endereços do destino é do seu processo de publicação.
Três etapas da migração
A amostra de dez páginas antes de prometer prazo
Antes de estimar, você captura dez páginas representativas com a janela aberta e olha cada resultado. Duas têm abas, uma tem uma tabela de parâmetros pesada, três têm caixas de aviso.
Em meia hora você sabe qual é o padrão de sujeira do site e o que vai sobrar de trabalho manual por página. Essa meia hora é o que separa uma estimativa de um palpite, e é a parte que costuma faltar quando a conversão em massa é a primeira decisão.
A seção de referência, página por página
A seção tem quarenta páginas, das quais vinte e seis ainda são usadas. Você percorre só essas, capturando com o atalho, e cada arquivo cai na subpasta espelhada da seção.
A revisão passa a ser sobre conteúdo: o que está desatualizado, o que precisa reescrever. Nenhum tempo vai para arrancar barra lateral e seletor de versão do topo do arquivo – nas 512 páginas medidas não sobrou um resto de tag HTML.
A wiki interna que não tem exportação
A base interna está atrás de SSO e não oferece exportação. Você abre as páginas como já abriria e captura: a extensão lê o que o navegador renderizou para a sua sessão.
Nada daquele material sai da máquina, porque a extensão não faz requisição de rede nenhuma. O que sai são arquivos .md na pasta do novo site, com o endereço interno no campo source para a revisão conseguir conferir cada um.
Comparado com as rotas de migração
Cada uma destas rotas já foi tentada em alguma migração de documentação. A terceira coluna diz o custo real de cada uma, sem abrir exceção para esta extensão.
| Como se migra hoje | O que você recebe | O que custa |
|---|---|---|
| Conversor em massa por script | Todas as páginas, de uma vez | Traz o entulho junto, e a faxina por arquivo é a parte que ninguém estima |
| Exportação do próprio CMS | O conteúdo no formato do sistema antigo | Só existe quando existe, e o formato exportado costuma ser HTML igualmente sujo |
| Copiar e colar página por página | O texto, com a estrutura que sobrevive à colagem | Bloco de código perde a marca, tabela quebra e a caixa de aviso vira parágrafo |
| Reescrever do zero | Documentação nova, do jeito certo | É o caminho mais caro, e o único que garante que nada foi herdado por engano |
| Salvar a página como HTML | A marcação inteira, com estilos | A limpeza depois é maior que a conversão, e o resultado ainda não é Markdown |
| Clean Clipper | Markdown limpo, com blocos marcados, tabelas e notas de rodapé | Sem rastreador, sem lote, sem reescrita de links internos; abas fechadas e imagens continuam sendo trabalho seu |
Quando a conversão sai incompleta
Por que só uma das abas veio no arquivo?
Porque o navegador só insere o conteúdo das outras quando você clica nelas. A extensão converte o DOM renderizado, e uma aba fechada não está lá. Em página de instalação com abas por sistema operacional ou gerenciador de pacotes, capture uma vez por aba, ou abra todas antes se o site permitir. Quando o site desenha todas e apenas esconde com estilo, todas vêm, uma depois da outra.
Por que os links internos continuam apontando para o site antigo?
Porque a extensão não sabe qual vai ser a estrutura de endereços do destino, e chutar produziria links quebrados no site novo. Os links saem exatamente como estavam, o que também é o que permite conferi-los durante a revisão. A reescrita para os endereços finais é uma etapa do seu processo de publicação, e costuma ser uma passada de busca e substituição.
Por que a caixa de aviso virou uma citação?
Porque o Markdown não tem sintaxe padrão para caixa de aviso, e cada gerador inventou a sua. Converter para a sintaxe de um deles quebraria em todos os outros. O conteúdo é preservado como citação em bloco, com o rótulo original na primeira linha, e uma substituição por expressão regular converte tudo para a sintaxe do seu gerador de uma vez.
Por que sumiu uma seção que existia na página?
Se ela tinha título vazio, foi descartada de propósito: título sem texto é artefato comum de bloco de navegação, e mantê-lo criaria uma seção fantasma no sumário do site novo. Se a seção tinha conteúdo e sumiu, quase sempre ela estava numa sanfona fechada, ou era carregada só ao rolar. Expanda, role até o fim e capture de novo.
Onde ele para
Não existe rastreador: é uma página por vez, a que está aberta, e um site com quatrocentas páginas continua sendo quatrocentas capturas. Ele não reescreve links internos para os endereços do destino, não baixa imagem – o link segue apontando para o site original – e não converte caixa de aviso em sintaxe de nenhum gerador específico, porque o Markdown não tem uma padrão. Título vazio, artefato comum de bloco de navegação, é descartado em vez de virar seção fantasma.
Perguntas
A hierarquia de títulos é fiel?
E as caixas de aviso e destaque?
Ele dá conta de um site de documentação inteiro?
Os links internos são reescritos para o novo endereço?
As imagens vêm junto?
A marca de linguagem dos blocos de código sobrevive?
Dá para migrar uma base interna que não tem exportação?
Como fica o frontmatter no gerador de site estático?
title, source, date e extraction. A maioria dos geradores lê title direto; os campos que o seu tema não usar ficam ali sem efeito, ou você os desliga nas opções antes de começar a migração.