Converter arquivos Markdown em HTML ou PDF em segundos

Charlie Macnamara

Redator técnico e engenheiro de suporte · Escócia · Mostrar biografia

O Markdown ajuda quem cria conteúdo para a web, como eu, a escrever textos adequados para esse meio com facilidade. Ele oferece formatação suficiente para que as pessoas consigam entender o texto, enquanto os computadores podem renderizá-lo com estilo usando HTML e CSS. O Markdown é independente de plataforma, e sua sintaxe pode ser aprendida em apenas cinco minutos⁠. Embora algumas pessoas defendam que existem formatos superiores, não há dúvida de que o Markdown se tornou a língua franca entre desenvolvedores que escrevem posts de blog e documentação. Ele é usado até em muitas aplicações web do dia a dia, como Reddit, Gmail e GitHub. Se usar Markdown ainda não é algo natural para você, há muitos recursos disponíveis online, como esta folha de consulta⁠ que eu mantinha à mão quando dei meus primeiros passos.

Na última vez em que falamos sobre EN (English) o /document/convert, nosso Robot, no final de 2019, o Robot ainda estava em seus primeiros estágios e só podia converter entre os formatos SRT e VTT. Desde então, o Robot foi aprimorado com muitos formatos adicionais.

Hoje, tenho a satisfação de compartilhar que ampliamos o suporte a arquivos do /document/convert, nosso Robot, para incluir Markdown! Agora você pode transformar automaticamente arquivos Markdown em páginas web ou até PDFs. Gere rapidamente faturas, contratos ou formulários de pedidos de venda em Markdown, passe-os para o /document/convert, nosso Robot, e obtenha esses documentos renderizados como PDFs para salvar no seu bucket S3. Ou talvez você venda para empresas que exigem que a documentação seja fornecida em PDF? Integre a Transloadit ao seu CI e continue escrevendo em Markdown 😄

Como converter de Markdown para HTML/PDF

Um novo parâmetro do /document/convert, nosso Robot, é markdown_format. Esse parâmetro é necessário porque o Markdown tem várias variantes⁠, cada uma com suas próprias diferenças sutis. Atualmente, a Transloadit aceita "commonmark" e "gfm" (GitHub Flavored Markdown) como valores.

Como mencionamos acima, os arquivos de entrada em Markdown podem ser convertidos em "html" ou "pdf", combinando esse novo parâmetro com o parâmetro format, que já existia.

Para orientar você no uso desse novo recurso, criamos o script abaixo:

Antes de executá-lo, crie sua própria credencial de Template para o Amazon S3 com um nome, usando o guia de configuração do S3 EN (English). Substitua YOUR_AWS_CREDENTIALS pelo nome salvo dessa credencial. Use um bucket privado com S3 Block Public Access habilitado e não forneça cabeçalhos de ACL ou de concessão de permissões. Definir acl como bucket-default omite o cabeçalho de ACL gerado; isso não torna o bucket privado.

// yarn add transloadit@3
const Transloadit = require('transloadit')

;(async () => {
  const transloadit = new Transloadit({
    authKey: process.env.TRANSLOADIT_AUTH_KEY,
    authSecret: process.env.TRANSLOADIT_AUTH_SECRET,
  })

  const assemblyStatus = await transloadit.createAssembly({
    waitForCompletion: true,
    params: {
      steps: {
        imported: {
          robot: '/http/import',
          url: 'https://raw.githubusercontent.com/transloadit/uppy/master/README.md',
        },
        converted: {
          use: 'imported',
          robot: '/document/convert',
          format: 'pdf',
          markdown_format: 'gfm',
        },
        thumbed: {
          use: 'converted',
          robot: '/document/thumbs',
          density: '300',
          trim_whitespace: false,
        },
        exported: {
          use: ['converted', 'thumbed'],
          robot: '/s3/store',
          credentials: 'YOUR_AWS_CREDENTIALS',
          acl: 'bucket-default',
        },
      },
    },
  })

  const pdf = assemblyStatus.results.converted[0]
  const thumb = assemblyStatus.results.thumbed[0]

  console.log(`Your PDF (${pdf.meta.page_count} pages) is ready at: ${pdf.ssl_url}`)
  console.log(`Here's a thumbnail of the first page: ${thumb.ssl_url}`)
})().catch((err) => {
  console.log(err)
  process.exit(1)
})

Este é um script Node.js, mas agora o fluxo de trabalho pode ser integrado à sua aplicação web ou móvel, ao seu serviço de back-end ou ao seu utilitário de linha de comando por meio de 20 SDKs práticos, como Uppy⁠ ou o SDK Go, e também diretamente pela nossa REST API JSON.

Nosso script é composto de alguns Steps:

• Importar um arquivo Markdown usando o /http/import, nosso Robot
• Converter esse Markdown em PDF
• Criar miniaturas de prévia de cada página do PDF usando o /document/thumbs, nosso Robot
• Salvar os arquivos resultantes no S3

Para executar o script, usamos os seguintes comandos:

# Find your Auth Key and Auth Secret: https://transloadit.com/docs/api/authentication/
export TRANSLOADIT_AUTH_KEY=****
export TRANSLOADIT_AUTH_SECRET=********
node md-to-pdf.js

O script imprime as URLs do PDF e da miniatura. Uma URL retornada não concede acesso público de leitura a um objeto privado; você precisa de uma autorização de leitura separada para recuperá-lo. Esta miniatura de exemplo mostra o Markdown renderizado:

Você verá que nosso PDF foi renderizado com o estilo Markdown do GitHub. Esses temas⁠ pertencem ao renderizador de Markdown, e não ao Markdown em si. Para controlar o tema de renderização, use o parâmetro markdown_theme. Atualmente, dois valores são aceitos: "github" (padrão) e "bare".

Para concluir

É isso! Esperamos que você inclua o /document/convert, nosso Robot aprimorado, no seu fluxo de trabalho com a Transloadit. E, como sempre, entre em contato pelo Twitter⁠ se tiver algum comentário. Saiba que a Transloadit oferece generosos 5 GB/mês de tráfego com nosso plano Community gratuito. Assim, qualquer desenvolvedor pode usar esse recurso sem precisar usar o cartão de crédito. 5 GB equivalem a muitos PDFs, então considere criar uma conta 😄