Algumas notas sobre a atualização de Hugo

AVISO: Este é um post sobre o yakshave muito chato, provavelmente apenas de interesse para as pessoas que estão tentando atualizar Hugo de uma versão muito antiga para uma nova versão. Mas o que são blogs para se não documentarem os iaques muito chatos de tempos em tempos?

Então, ontem eu decidi tentar atualizar Hugo. Não há motivo real para fazer isso – eu uso o Hugo versão 0.40 para gerar este blog desde 2018, funciona bem e não tenho nenhum problema com ele. Mas pensei – talvez não seja tão difícil quanto eu penso, e eu meio que gosto de uma tarefa tediosa do computador às vezes!

Pensei em documentar o que aprendi ao longo do caminho, caso seja útil para qualquer outra pessoa que faça essa migração muito específica. Atualizei de Hugo v0.40 (de 2018) para v0.135 (de 2024).

Aqui estão a maioria das mudanças que tive que fazer:

Alterar 1: template "theme/partials/thing.html é agora partial thing.html

Eu tive que substituir várias instâncias de {{ template "theme/partials/header.html" . }} com {{ partial "header.html" . }}.

Isso aconteceu em v0.42:

Agora, virtualizamos os sistemas de arquivos para arquivos de projeto e tema. Isso torna tudo mais simples, mais rápido e mais poderoso. Mas também significa que as pesquisas de modelo no formulário {{modelo “tema/parcials/pagination.html”. }} não funcionará mais. Essa sintaxe nunca foi documentada, portanto, não se espera que esteja em uso amplo.

Alterar 2: .Data.Pages é agora site.RegularPages

Isso parece ser discutido nas notas de lançamento para 0,57.2

Eu só precisava substituir .Data.Pages com site.RegularPages No modelo na página inicial, bem como no meu modelo de alimentação RSS.

Alterar 3: .Next e .Prev foi virado

Eu tive esse comentário na parte do meu tema em que vinculei a próxima/anterior postagem do blog:

“Next” e “Anterior” em Hugo aparentemente significam o oposto do que eu pensaria que eles significariam intuitivamente. Eu esperaria que “o próximo” signifique “no futuro” e “anterior” como significar “no passado”, mas é o oposto

Parece que eles mudaram isso no AD705AAC064, de modo que “o próximo” realmente está no futuro e “Prev” na verdade está no passado. Eu definitivamente acho o novo comportamento mais intuitivo.

Download do Hugo Changelogs com um script

Descobrir o porquê/quando todas essas mudanças aconteceram foi um pouco difícil. Acabei hackeando um script bash para baixar todos os Changelogs do GitHub como arquivos de texto, que eu poderia ter grep para tentar descobrir o que aconteceu. Acontece que é muito fácil obter todos os Changelogs da API do GitHub.

Até agora, tudo não era tão ruim – também houve uma mudança em torno das taxonomias que não consigo explicar, mas tudo era bastante gerenciável, mas então chegamos ao realmente difícil: o renderizador de Markdown.

Mudança 4: O Renderizador de Markdown (Blackfriday -> Goldmark)

O renderizador Blackfriday Markdown (que anteriormente era o padrão) foi removido em v0.100.0. Isso parece razoável:

Ele está depreciado há muito tempo, sua versão V1 não é mais mantida e há muitos problemas conhecidos. A Goldmark deve ser uma substituição madura até agora.

Corrigir todas as minhas mudanças de marcha foi uma dor enorme – acabei tendo que atualizar 80 arquivos de marcação diferentes (de 700) para que eles renderizassem corretamente, e não tenho certeza

Por que se preocupar em mudar de renderizadores?

A pergunta óbvia aqui é: por que se preocupar até tentar atualizar Hugo, se eu tiver que mudar de renderizadores de marcação? Meu site antigo estava funcionando totalmente bem e acho que não era necessariamente um bom
O uso do tempo, mas a única razão pela qual acho que pode ser útil no futuro é que o novo renderizador (GoldMark) use o padrão de marcação do Commonmark, que espero que seja um pouco mais à prova de futuro. Então, talvez eu não tenha que passar por isso de novo? Vamos ver.

Além disso, o novo Renderer da Goldmark corrige alguns problemas que eu tive (mas não sabia que tinha) com citações inteligentes e como as listas/blocos interagem.

Encontrando todos os problemas de remarca: o processo

A parte difícil dessa mudança de remarca foi descobrir o que mudou. Quase todos os problemas (incluindo #2 e #3 acima) apenas quebraram o site silenciosamente, eles não causaram erros ou nada. Então, eu tive que diferenciar o html para caçá -los.

Aqui está o que eu acabei fazendo:

1. Gerar o site com a versão antiga, coloque -a em public_old
2. Gerar a nova versão, coloque -a em public
3. Diff cada arquivo html em public/ e public_old com este script diff.sh e coloque os resultados em um diffs/ pasta
4. Execute variações em find diffs -type f | xargs cat | grep -C 5 '(31m|32m)' | less -r repetidamente para olhar para todas as mudanças até que eu encontrei algo que parecia errado
5. Atualize a remarcação para corrigir o problema
6. Repita até que tudo parecia bem

(o grep 31m|32m coisa é procurar texto vermelho/verde no diff)

Isso consumia muito tempo, mas foi um pouco divertido por algum motivo, então eu continuei fazendo isso até que parecia que nada muito horrível foi deixado.

as novas regras de remarcação

Aqui está uma lista de todos os tipos de alterações de marcação que eu tive que fazer. É muito possível que tudo isso seja extremamente específico para mim, mas demorei muito tempo para descobrir tudo, então talvez isso seja útil para uma outra pessoa que encontre isso no futuro.

4.1: Misturando HTML e Markdown

Isso não funciona mais (não expande o link):

(a link)(https://example.com)

Eu preciso fazer isso em vez disso:

(a link)(https://example.com)

Isso também funciona:

 (a link)(https://example.com) 

4.2: << é alterado para «

Eu não queria isso, então precisava configurar:

markup:
  goldmark:
    extensions:
      typographer:
        leftAngleQuote: '<<'
        rightAngleQuote: '>>'

4.3: As listas aninhadas às vezes precisam de 4 recuos espaciais

Isso não renderiza mais como uma lista aninhada se eu apenas recuar por 2 espaços, preciso colocar 4 espaços.

1. a
  * b
  * c
2. b

O problema é que a quantidade de recuo necessária depende do tamanho dos marcadores da lista. Aqui está uma referência na marca comum para isso.

4.4: BlockQuotes dentro das listas funcionam melhor

Anteriormente o > quote Aqui não se renderizou como um bloco e com o novo renderizador, ele faz.

* something
> quote
* something else

Encontrei um monte de remarcado que estava meio quebrado (o que eu não havia notado) que funciona melhor com o novo renderizador, e este é um exemplo disso.

As listas dentro do BlockQuotes também parecem funcionar melhor.

4.5: Chefes dentro das listas

Anteriormente, isso não se renderizou como título, mas agora o faz. Então eu precisava substituir o # com #.

* # passengers: 20

4.6: + ou 1) No início da linha, faz uma lista

Eu tinha algo que parecia assim:

`1 / (1
+ exp(-1)) = 0.73`

Com o Blackfriday, ele renderizou assim:

1 / (1
+ exp(-1)) = 0.73

E com a Goldmark, ele renderizou assim:

`1 / (1

A mesma coisa se houvesse um acidental 1) No início de uma linha, como neste trecho de Marydown

I set up a small Hadoop cluster (1 master, 2 workers, replication set to 
1) on 

Para consertar isso, eu só tive que reescrever a linha para que o + não foi o primeiro personagem.

O Markdown é formatado dessa maneira, porque eu encerro muito a minha marcação para 80 caracteres e o embrulho não é muito sensível ao contexto.

4.7: Não há mais citações inteligentes em blocos de código

Havia um monte de lugares onde o antigo renderizador (Blackfriday) estava fazendo coisas indesejadas em blocos de código, como substituir ... com … ou substituindo cotações por citações inteligentes. Eu não tinha percebido que isso estava acontecendo e fiquei muito feliz por consertá -lo.

4.8: Melhor gerenciamento de cotação

A maneira como isso é renderizada melhorou:

"Oh, *interesting*!"

• velho: “Oh, interessante! “
• Novo: “Oh, interessante! ”

Antes de haver duas citações inteligentes deixadas, agora as citações correspondem.

4.9: As imagens não estão mais envolvidas em um p marcação

Anteriormente, se eu tivesse uma imagem como esta:

seria embrulhado em um tag, now it doesn’t anymore. I dealt with this
just by adding a margin-bottom: 0.75em Para imagens no CSS, espero que isso as faça exibir bem o suficiente.

markup:
  highlight:
    codeFences: false
  goldmark:
    renderer:
      unsafe: true
    parser:
      autoHeadingIDType: blackfriday