Markdown-Dateien in Sekunden in HTML oder PDF umwandeln

Charlie Macnamara

Technischer Redakteur & Support-Techniker · Schottland · Bio anzeigen

Wer wie ich Webinhalte erstellt, kann mit Markdown einfach Texte schreiben, die sich fürs Web eignen. Markdown bietet gerade genug Formatierung, damit Menschen den Text noch gut verstehen und Computer ihn mit HTML und CSS ansprechend darstellen können. Markdown ist plattformunabhängig, und seine Syntax lässt sich in nur fünf Minuten⁠ erlernen. Manche halten andere Formate für überlegen. Unbestritten ist jedoch, dass Markdown zur Lingua franca unter Entwicklern geworden ist, die Blogbeiträge und Dokumentation schreiben. Es wird sogar in vielen alltäglichen Webanwendungen wie Reddit, Gmail und GitHub verwendet. Wenn Ihnen Markdown noch nicht in Fleisch und Blut übergegangen ist, finden Sie online viele hilfreiche Ressourcen, etwa diesen Spickzettel⁠, den ich bei meinen ersten Schritten griffbereit hatte.

Als wir Ende 2019 zuletzt über unseren Robot /document/convert berichteten, steckte der Robot noch in den Kinderschuhen und konnte nur zwischen den Formaten SRT und VTT konvertieren. Seitdem unterstützt der Robot viele weitere Formate.

Heute freue ich mich, Ihnen mitzuteilen, dass unser Robot /document/convert jetzt auch Markdown unterstützt! Sie können Markdown-Dateien nun automatisch in Webseiten oder sogar PDFs umwandeln. Erstellen Sie schnell Rechnungen, Verträge oder Bestellformulare als Markdown und übergeben Sie sie unserem Robot /document/convert. Lassen Sie sie als PDFs rendern und in Ihrem S3-Bucket speichern. Oder verkaufen Sie an Unternehmen, die Dokumentation als PDF verlangen? Binden Sie Transloadit in Ihre CI ein und schreiben Sie weiterhin Markdown 😄

Wie konvertieren Sie Markdown in HTML/PDF?

Ein neuer Parameter für den Robot /document/convert ist markdown_format. Dieser Parameter ist nötig, da Markdown mehrere Varianten⁠ mit jeweils feinen Unterschieden hat. Transloadit unterstützt derzeit "commonmark" und "gfm" (GitHub Flavored Markdown) als Werte.

Wie oben erwähnt, lassen sich Eingabedateien in Markdown entweder in "html" oder "pdf" konvertieren, indem Sie diesen neuen Parameter mit unserem bereits vorhandenen Parameter format kombinieren.

Um Sie durch die Nutzung dieser neuen Funktion zu führen, haben wir das folgende Skript erstellt:

Legen Sie vor dem Ausführen für Amazon S3 einen eigenen benannten Eintrag mit Template-Zugangsdaten an. Nutzen Sie dafür die S3-Einrichtungsanleitung. Ersetzen Sie YOUR_AWS_CREDENTIALS durch den gespeicherten Namen dieses Eintrags. Verwenden Sie einen privaten Bucket mit aktiviertem S3 Block Public Access und geben Sie keine ACL- oder Grant-Header an. Wenn Sie acl auf bucket-default setzen, wird der generierte ACL-Header weggelassen; dadurch wird der Bucket nicht privat.

// 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)
})

Dies ist ein Node.js-Skript. Der Workflow lässt sich nun aber auch in Ihre Web- oder Mobilanwendung, Ihren Backend-Dienst oder Ihr Kommandozeilenprogramm integrieren, mithilfe von 20 praktischen SDKs wie Uppy⁠ oder dem Go SDK sowie direkt mit unserer JSON REST API.

Unser Skript besteht aus einigen Steps:

• Importieren einer Markdown-Datei mit unserem Robot /http/import
• Konvertieren dieser Markdown-Datei in PDF
• Erstellen von Thumbnails zur Vorschau für jede PDF-Seite mit dem Robot /document/thumbs
• Speichern der Ergebnisdateien in S3

Zum Ausführen des Skripts haben wir die folgenden Befehle verwendet:

# 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

Das Skript gibt die PDF-URL und die Thumbnail-URL aus. Eine zurückgegebene URL gewährt keinen öffentlichen Lesezugriff auf ein privates Objekt; zum Abrufen benötigen Sie eine separate Leseberechtigung. Dieses Beispiel-Thumbnail zeigt das gerenderte Markdown:

Sie sehen, dass unsere PDF-Datei im GitHub-Markdown-Stil gerendert wurde. Diese Themes⁠ gehören zum Markdown-Renderer und nicht zu Markdown selbst. Um das Theme für die Darstellung festzulegen, verwenden Sie den Parameter markdown_theme. Derzeit werden zwei Werte unterstützt: "github" (Standard) und "bare".

Zum Abschluss

Das war’s! Wir freuen uns, wenn Sie unseren verbesserten Robot /document/convert in Ihren Transloadit-Workflow einbinden. Wenn Sie Feedback haben, melden Sie sich wie gewohnt auf Twitter⁠. Transloadit bietet Ihnen mit dem kostenlosen Community-Tarif beachtliche 5 GB Traffic pro Monat. Damit können alle Entwickler diese Funktion nutzen, ohne ihre Kreditkarte einzusetzen. 5 GB reichen für viele PDFs, also erwägen Sie eine Registrierung 😄