Markdown-Dateien in Sekunden in HTML oder PDF umwandeln

Charlie Macnamara

Technischer Redakteur & Support-Techniker · Schottland · Bio anzeigen

Markdown hilft Erstellern von Webinhalten wie mir, mühelos Texte zu schreiben, die sich für das Web eignen. Es erlaubt gerade genug Formatierung, damit Menschen den Text noch verstehen, während Computer ihn mit HTML und CSS stilvoll 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, doch es steht außer Frage, 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. Falls Ihnen Markdown noch nicht in Fleisch und Blut übergegangen ist, finden Sie online viele Ressourcen, etwa dieses Cheatsheet⁠, das ich bei meinen ersten Schritten stets zur Hand hatte.

Als wir Ende 2019 das letzte Mal EN (English) über unseren Robot /document/convert geschrieben haben, steckte der Robot noch in den Kinderschuhen und konnte nur zwischen den Formaten SRT und VTT umwandeln. Seitdem wurde der Robot um viele weitere Formate erweitert.

Heute freue ich mich, mitteilen zu können, dass wir die Dateiunterstützung in unserem Robot /document/convert auf Markdown erweitert haben! Sie können Markdown-Dateien jetzt automatisch in Webseiten oder sogar PDFs verwandeln. Erstellen Sie Rechnungen, Verträge oder Auftragsformulare schnell als Markdown, übergeben Sie sie an unseren Robot /document/convert und lassen Sie sie als PDFs rendern, um sie in Ihrem S3-Bucket zu speichern. Oder verkaufen Sie an Unternehmen, die Dokumentation als PDF verlangen? Binden Sie Transloadit in Ihre CI ein und schreiben Sie weiterhin Markdown 😄

So wandeln Sie Markdown in html/pdf um

Ein neuer Parameter für den Robot /document/convert ist markdown_format. Dieser Parameter ist notwendig, da Markdown in mehreren Varianten⁠ existiert, die jeweils ihre eigenen feinen Unterschiede mitbringen. Transloadit unterstützt derzeit die Werte "commonmark" und "gfm" (GitHub Flavored Markdown).

Wie oben erwähnt, lassen sich Eingabedateien in Markdown entweder in "html" oder "pdf" umwandeln, 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:

// 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: 'demo_s3_credentials',
          url_prefix: 'https://demos.transloadit.com/',
        },
      },
    },
  })

  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, doch der Workflow lässt sich jetzt mit 20 praktischen SDKs wie Uppy⁠ oder dem Go SDK sowie direkt über unsere JSON-REST-API in Ihre Web- oder Mobile-App, Ihren Backend-Dienst oder Ihr Kommandozeilen-Tool integrieren.

Unser Skript besteht aus einigen Steps:

• Eine Markdown-Datei mit dem Robot /http/import importieren
• Dieses Markdown in PDF umwandeln
• Vorschau-Thumbnails für jede Seite des PDFs mit dem Robot /document/thumbs erstellen
• Die resultierenden Dateien in S3 speichern

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 URLs des PDFs und der Thumbnails aus. Dieses Beispiel-Thumbnail zeigt das gerenderte Markdown:

Sie sehen, dass unser PDF im GitHub-Markdown-Stil gerendert wurde. Ähnlich wie bei der Vielfalt der Formate unterstützt Markdown nämlich auch zahlreiche Themes⁠. Um diese Themes zu steuern, verwenden Sie den Parameter markdown_theme. Derzeit werden zwei Werte unterstützt: "github" (Standard) und "bare".

Zum Abschluss

Das war's! Wir hoffen, dass Sie unseren verbesserten Robot /document/convert in Ihren Transloadit-Workflow einbinden. Und wie immer gilt: Bitte melden Sie sich auf Twitter⁠, wenn Sie Feedback haben. Beachten Sie, dass Transloadit mit unserem kostenlosen Community-Tarif stattliche 5 GB Traffic pro Monat bietet. So kann jeder Entwickler dies nutzen, ohne die Kreditkarte zu zücken. 5 GB reichen für sehr viele PDFs, denken Sie also über eine Registrierung nach 😄