Sugestão de ferramenta (SSG)

[neninja]

Longe de mim querer quebrar todo esforço já feito, mas talvez não seria mais interessante utilizar um gerador de sites estáticos (SSG) para evitar que cada post seja feito com html puro?

Vantagens:

• Adição de tags, resumos e outros metadados por post
• Focar mais no conteúdo escrito com markdown do que com html
• Organização de templates e posts mais simples

Semana passada tava testando o hugo e consegui fazer com que o build fosse a cada push na branch main com github actions:

• blog simples com hugo
• projeto
• exemplo de post (repare no "Edite esse post")
• post em markdown
• action

[psygo]

Minha opinião é em geral ser contra frameworks. Alguns motivos:

• A princípio, ajuda, mas acaba sendo mais uma dependência para entender e administrar.
• Estar o mais perto possível do que será entregue para o usuário final tende a gerar muito mais flexibilidade e possibilidades.
• No caso específico de Markdown vs HTML, o custo de fazer em HTML direto não me parece ser tão grande, ainda mais porque pode-se, à parte, simplesmente criar o artigo em Markdown de qualquer maneira e, depois utilizar uma das milhões de ferramentas online que convertem Markdown para HTML.

De qualquer maneira, habilitar criação de posts em Markdown para este site especificamente seria bom em absoluto, se fosse mais uma maneira de fazê-lo. Por exemplo, se você quiser/puder criar um script na pasta ferramentas/ utilizando algum programa npm que converta Markdown em HTML, acho que seria muito benéfico. Porém, vale notar que, idealmente, este site não é 100% conteúdo estático: por exemplo, há já Web Components personalizados sendo registrados via TS/JS e também há bibliotecas como Glift e WGo.js como visualizadores de SGFs. Não sei ao certo se esses "compiladores" Markdown têm suporte para esse tipo de coisa.

[neninja]

TL;DR: A principal vantagem de um SSG (lista de popularidade) é justamente evitar escrever html para focar no conteúdo em si, se não vê vantagem acho que não vale a pena.

Concordo com a ideia de quanto menos dependência melhor, principalmente a nível de um framework. Mas acho que vale dizer algumas coisas:

• Existem vários SSG populares que leem markdown e convertem para html. Caso topassem usar agora e depois trocassem de ideia para outro, os conteúdos permaneceriam intactos, o que muda é como criar template, partials e etc
• Caso quisessem retroceder ao html pois não curtiram SSGs, basta buildar a página e pegar o resultado em html
• o Hugo é uma cli de linha de comando, para utilizá-lo só precisa baixar o executável. Sem a necessidade de ter um ambiente muito específico para a ferramenta (o jekyll já existe um ambiente com ruby)

E agora pontuando sobre o que listou sobre frameworks:

...dependência para entender e administrar

• Não é tão complexo o quanto parece e o custo de administração com vários htmls é maior. Ex: caso queira adicionar um css vai ter um trabalho cansativo, caso queira mudar um menu, footer, lista de posts e etc igual.

Estar o mais perto possível do que será entregue para o usuário final tende a gerar muito mais flexibilidade e possibilidades

• Nesse caso com html, com um custo de manutenção alto como comentei acima

...o custo de fazer em HTML direto não me parece ser tão grande... ...ainda mais porque pode-se, à parte, simplesmente criar o artigo em Markdown de qualquer maneira e, depois utilizar uma das milhões de ferramentas online que convertem Markdown para HTML

• Ambos são linguagens de marcação, sendo HTML mais verboso e com mais possibilidades. Concordo que não é o fim do mundo, porém convenhamos que é bem melhor ler markdown no editor por ser mais simples. Outra: html exige convenções blockquote pra citação, code pra código, em para itálico etc.
• Concordo, por mais que seja uma barreira inicial, resolve na criação de posts. Só não resolve para manter o post (corrigir/atualizar)

Sobre libs js, o github pages dispõe só conteúdo estático, pois ele só entrega html + assets, não existe processamento por requisição. O que não pode ser feito é backend com express, php e etc

[psygo]

Se a pessoa quiser escrever em Markdown e salvar na pasta do artigo, não há problema nenhum. Só que ela vai precisar transpilar o Markdown para HTML de qualquer maneira — ela pode fazer no Word também se preferir. E essa compilação vai ficar cada vez mais complexa se quisermos automatizar tudo, pois estamos utilizando componentes web e metadados personalizados. Isso tudo me soa como overengineering no final.

Sobre libs js, o github pages dispõe só conteúdo estático, pois ele só entrega html + assets, não existe processamento por requisição. O que não pode ser feito é backend com express, php e etc

O conteúdo é estático do ponto de vista do servidor, mas não sei se concordo que também o é do ponto de vista do cliente, pois há TS/JS sendo rodado dentro da página HTML. Por exemplo, casos como codigo/ui/tabela_jogadores.ts talvez sejam complicados de se lidar com Markdown. O caso da tabela de jogadores não é mesmo de artigos realmente, mas qualquer coisa um pouco mais dinâmica e programática começa a ficar difícil de se lidar puramente com Markdown.

Existem vários SSG populares que leem markdown e convertem para html. Caso topassem usar agora e depois trocassem de ideia para outro, os conteúdos permaneceriam intactos, o que muda é como criar template, partials e etc

Apesar de que HTML é realmente prolixo, só existe um HTML relevante no planeta. Aprende-se somente uma vez. Eu e outras pessoas não vão ser facilmente convencidas a possivelmente ter de aprender múltiplos compiladores de Markdown-HTML.

---

Não sou totalmente contra tudo isso, só acho que deveria ser mais uma maneira e não a dependência principal. Se você quiser/puder — ou outros convergirem —, crie um PR que, dentre outros itens:

1. Adicione um pequeno manual ao README.md de como criar um artigo em Markdown e compilá-lo para HTML.
   • É preciso também levar em conta como adicionar metadados e componentes web personalizados a este site.
2. Adicione um script à pasta ferramentas/ para ter algo executável e suscinto sobre o processo.

[psygo]

E, em relação a verbosidade e o fato de que, sim, há muito mais informação na tela do que se gostaria quando estamos escrevendo os HTMLs, isso tudo se minimiza consideravelmente se, em paralelo, o desenvolvedor está compilando tudo dinamicamente (--watch) e visualizando o resultado localmente no browser.

[neninja]

... isso tudo me soa como overengineering no final ...só acho que deveria ser mais uma maneira e não a dependência principal.

• Como você vê mais esforço que recompensa e não quer depender unicamente de uma ferramenta, concordo. Se for esse o consenso final acho que nem tem mais o que refletir.
• Em breve vou forkar o repo e reestruturá-lo padrão hugo para ser mais fácil o entendimento do resultado final que estou sugerindo, se gostarem submeto PR. Se puder manter a issue aberta até esse momento agradeço.

... casos como codigo/ui/tabela_jogadores.ts talvez sejam complicados de se lidar com Markdown.

• O ts precisa ser transpilado, isso faria parte do processo de build da aplicação, mas com relação ao desenvolvimento de ts junto ao hugo aparentemente já foi feito antes.
• Pelo que me lembro não existe problema importar dentro do markdown um script de js, pois o import vai ser mantido no momento da transpilação para html.
• Se esse script for corriqueiro, confesso ser muito novo no Go (que por sinal conheci pelo seu canal no youtube e blog :blush:), pode ser criado um template especifico para esse tipo de post (facilitando mais ainda a diversificação de posts).

... só existe um HTML relevante no planeta. Aprende-se somente uma vez. Eu e outras pessoas não vão ser facilmente convencidas a possivelmente ter de aprender múltiplos compiladores de Markdown-HTML.

• Concordo, mas reitero que a ferramenta não é complicada e traz muito mais ganhos por existir um processo de build, listo novamente:
• Escrita em markdown do conteúdo do post, não se preocupando com <head>, seo, tags, indentação e etc. Outra: post podem ser criados como modo rascunho, desse modo eles não são buildados até sua finalização.
• O processo de build permite identificar data de posts, autores, tags, categorias, seções e diversos outros metadados para listagens, sugestões e etc
• Separando conteúdo, template e tema fica mais fácil dar manutenção no site
• Build final é apenas html sem javascript para inserir menus, headers, footers e etc

...isso tudo se minimiza consideravelmente se, em paralelo, o desenvolvedor está compilando tudo dinamicamente (--watch) e visualizando o resultado localmente no browser

• Concordo, porém acho estranho que tu precise se preocupar com a renderização do post durante a escrita dele.

[neninja]

Refatoração para o Hugo: https://github.com/nenitf/nihonkiin.com.br

Notem que:

• Mantive a mesma separação por conteúdo e artigos
• Criei um layout específico para artigos que utilizem glift
• Separei os eventos e a trilha principal do html
• Utilizei as funções do Hugo para listar os últimos artigos, incluindo informações como título, data e autor
• Reutilizei o "componente" calendário de eventos tanto na index quanto na sua página específica de eventos

O código final dos artigos ficou meia boca, alguns mantive html outros não e acredito que precisaria de um cuidado maior na revisão de links. Portanto o fork não está pronto para PR, mas caso gostem da ideia do Hugo podemos trabalhar nele.

[psygo]

Bacana que você fez um exemplo completo, e até pediria para você criar um PR com ele, sendo este aprovado ou não. É legal ter exemplos como esses registrados.

Porém, da minha parte, ainda não consigo me convencer. A adição estrutural e linguística que você teve de fazer é bem considerável na minha opinião, e realmente me parece overengineering — acaba sendo uma linguagem dentro de uma outra linguagem.

(...) porém acho estranho que tu precise se preocupar com a renderização do post durante a escrita dele.

Discordo. Construir o site localmente é importante para minimizar a probabilidade de bugs, sejam eles visuais ou lógicos. Além disso, construir o site localmente e utilizá-lo durante a edição deixa o desenvolvedor o mais próximo possível da experiência real do usuário.

Pelo que me lembro não existe problema importar dentro do markdown um script de js, pois o import vai ser mantido no momento da transpilação para html.

Bom saber que há suporte para esse tipo de coisa. No geral, eu tenho a impressão que, para blogs simples, essa ferramenta é ideal, mas, à medida que o site vai se complicando — algo que inevitavelmente ocorrerá com este — o custo-benefício da ferramenta diminui, ao ponto que HTML puro passa novamente a ser adequado.

---

De qualquer maneira, acho que já argumentei meus pensamentos o suficiente para revelar minha opinião. Vou deixar para o @laercioskt e o @sagemerlin e outros usuários darem seus respectivos feedbacks antes de tomarmos uma decisão.

---

que por sinal conheci pelo seu canal no youtube e blog

Obrigado pela audiência! :)