Trampolim - conversor e publicador web de arquivos em Markdown

O trampolim é um script para converter um arquivo em Markdown para HTML responsivo e fazer o upload para sua publicação em um servidor web.

Por Augusto Campos - https://augustocampos.net/

O trampolim.sh foi criado para automatizar o meu fluxo de publicação de arquivos em Markdown e ser utilizado em minhas automações pessoais, especificamente na intenção de facilitar o compartilhamento na web (em HTML) da nota (em Markdown) que estiver em edição no Obsidian no meu computador.

O Obsidian conta com recursos pagos e plugins gratuitos para fazer esse mesmo procedimento, e eu recomendo que você os prefira. Você é bem-vindo se quiser usar o trampolim também, mas saiba que não há suporte, nem garantia.

Download do Trampolim

O trampolim é distribuído em um arquivo .tar.gz que contém:

• o script trampolim.sh
• uma cópia deste arquivo leiame.md
  • um diretório html, contendo um subdiretório estilo, contendo um tema trampolim.css
  • um diretório modelo, contendo um arquivo base.html
• O arquivo trampolim.css distribuído inclui o tema pandoc.css criado por Pascal Hertleif (@killercup@mastodon.social)
• O arquivo base.html é derivado do template default gerado pelo comando pandoc -D html.

Link para download e licença:

• Download: trampolim-0.6.16.tar.gz
• Desenvolvedores podem ficar à vontade caso queiram criar um fork. Esta versão é disponibilizada nos termos da licença Apache 2.0, ou da licença mencionada no cabeçalho de cada arquivo individual distribuído.

Instruções e informações técnicas

1. Parâmetros de chamada

• Esta versão pública do trampolim.sh recebe recebe 2 parâmetros, sendo o primeiro obrigatório e o segundo opcional.
• O primeiro parâmetro é o caminho (absoluto ou relativo) do arquivo em Markdown a ser convertido e publicado.
• O segundo parâmetro (opcional) é o caminho scp do diretório remoto para onde deve ser feito o upload, no formato usuário@servidor:diretório

2. Exemplos de chamada do script:

1. só converte para HTML, gravando o resultado no diretório html (ver abaixo): ./trampolim.sh "/Users/fulana/Obsidian/minhas-notas/nota de teste.md"

2. Converte para HTML, grava no diretório html e faz upload para o servidor: ./trampolim.sh "/Users/fulana/Obsidian/minhas-notas/nota de teste.md" "fulana@servidor.com.br:/home/fulana/web/arquivos"

3. Arquivos e diretórios

• Caso não exista, o script criará um diretório ‘html’ no mesmo diretório em que ele estiver instalado, e gravará nele cópias dos arquivos HTML que vier a gerar.
• Esse diretório ‘html’ pode conter um subdiretório chamado ‘estilo’. Se dentro desse subdiretório ‘estilo’ houver um arquivo ‘trampolim.css’ (i.e. html/estilo/trampolim.css), o trampolim.sh irá gerar arquivos HTML que referenciam esse arquivo css como sua folha de estilos. Neste caso, providencie para que no servidor haja também uma cópia do mesmo arquivo, com o nome de estilo/trampolim.css, relativo ao diretório em que o seu arquivo HTML for publicado.
• Caso exista um diretório ‘modelo’ no mesmo diretório em que o script estiver instalado, o script procurará nele, e usará caso encontre, os arquivos a seguir:
  • base.html: um arquivo no formato dos templates do Pandoc, para definir como deverá ser gerado o arquivo HTML (caso não seja encontrado, o Pandoc usará o seu template default).
  • rodape.html: se existir, será copiado imediatamente antes da tag /body do arquivo HTML gerado.

4. Metadados aproveitados do seu arquivo Markdown

• O script procura o primeiro título definido no arquivo Markdown de origem, e o usa para definir a tag title do arquivo HTML gerado.
• O script procura o primeiro parágrafo com mais do que 5 palavras do arquivo Markdown de origem, que não seja um título 1, e o usa para definir a tag meta description do arquivo HTML gerado.

5. Transferência para o servidor web

• A transferência só será tentada caso o script seja chamado com um segundo parâmetro, conforme exposto acima.
• Caso já haja um arquivo com o mesmo nome no diretório de destino do servidor, ele será sobrescrito, a não ser que a configuração do scp ou do servidor impeçam.
• Use o scp com segurança. A forma correta de evitar a digitação de senhas a cada upload é configurar e usar chaves, geralmente no diretório ~/.ssh. Consulte a documentação do SSH e do SCP em uso no seu ambiente.

6. Dependências

• O script trampolim.sh é em bash
• Suas dependências são: Pandoc (que faz o trabalho pesado de conversão de formatos), awk e scp
• As dependências devem estar todas no path do ambiente de execução.

7. Log

• Ao término de cada execução, o script grava no seu diretório html (veja acima) um arquivo lastlog.txt contendo o valor das suas variáveis, para debug.

FAQ do Trampolim

1 - Por que esse nome?

R. Um trampolim me parece uma metáfora interessante para a abordagem desse script, que impulsiona o conteúdo de um arquivo em Markdown para colocá-lo na grande piscina da web.

2 - O Trampolim está disponível para download?

R. Sim.

3 - O Trampolim é open source?

R. Sim, sob a licença Apache 2.0, ou a licença mencionada no cabeçalho de cada arquivo individual distribuído.

4 - O Trampolim é software livre?

R. Sim, sob a licença Apache 2.0, ou a licença mencionada no cabeçalho de cada arquivo individual distribuído.

5 - Fazer uma nova ferramenta para lidar com a conversão para HTML e upload não é reinventar a roda?

R. Sim, e gostei muito da minha nova roda, sob medida pra minha demanda.

6 - Eu não poderia fazer a mesma coisa com meia linha de Python?

R. Provavelmente sim, e tenho certeza que você se divertiria no processo.

7 - Eu não poderia fazer a mesma coisa com o Pandoc, um clips e um chiclete?

R. Provavelmente sim, e acho que você deveria tentar!

8 - Você chegou a testar a ferramenta Tal?

R. Provavelmente não, o que não quer dizer que ela não me atenderia, ou não lhe atenderia.

9 - Por que eu deveria usar o Trampolim, e não outra ferramenta?

R. Provavelmente você deveria usar a ferramenta de sua preferência.

10 - Por que o Trampolim não tem o recurso Tal?

R. Provavelmente eu não preciso dele, ou ele ainda consta na minha lista de pendências. Como o Trampolim é open source, os interessados poderão inclui-lo, se existirem e desejarem.

11 - Posso implantar o recurso TAL no Trampolim?

R. Sim, se desejar. Ele é open source. Faça um fork, cumpra os requisitos da licença, e divirta-se.

12 - Você vai inserir na sua versão o novo recurso que eu adicionar no meu fork?

R. Não sei, mas isso não deveria ser motivo para você adicionar, ou deixar de adicionar.

13 - Como posso te enviar a modificação que eu fiz?

R. Caso você deseje me enviar, a minha preferência é que você envie a descrição e um diff para o e-mail augusto@augustocampos.net, mas não posso me comprometer a analisá-lo.

14 - Por que você não implementou o Trampolim de tal outra forma, ou com tal outro recurso?

R. Eu o criei com uma finalidade específica, e ele o atende. Haveria muitas outras formas possíveis de implementar, e tenho certeza de que não será difícil encontrá-las em outras ferramentas, caso você não queira implementar pessoalmente.

15 - Por que você não colocou o Trampolim no repositório Tal ou no serviço on-line XYZ?

Eu gosto de disponibilizar código no meu próprio servidor, em arquivos .tar.gz.

16 - Por que o recurso X do Obsidian (ou da ferramenta XYZ) se perde ao transformar em HTML?

R. O Pandoc é amplo, mas os recursos das ferramentas baseadas em Markdown estão sempre se expandindo, e nem todos atendem aos padrões já suportados. A documentação do Pandoc explica como expandi-lo, se você desejar!

17 - Por que o Trampolim não funcionou no meu ambiente?

Difícil saber sem conhecer o seu ambiente! Mas verifique se as dependências mencionadas acima estão atendidas, e use as mensagens de erro e o arquivo de log para dar início à sua investigação.