Generieren Sie einen Pull-Request für statische Inhalte mit einem einfachen HTML-Formular

Jamstack gibt es in der Webseitenwelt schon seit Jahren. Statische Site-Generatoren (SSGs) — die oft Inhalte direkt in einem GitHub-Repository haben — sind ein wichtiger Teil dieser Geschichte. Das eröffnet die Idee, Beitragende zu haben, die Pull-Requests öffnen können, um Inhalte hinzuzufügen, zu ändern oder zu bearbeiten. Sehr nützlich!

Beispiele hierfür sind

Die Serverless Site von CSS-Tricks (Repo)
Die Coding Fonts Site von CSS-Tricks (Repo)
Die Site Generator Site von Jamstack (Repo)
Meine eigene Free Developer Stuff Site (Repo)

Warum mit einem statischen Ansatz für Websites?

Wenn wir inhaltsbasierte Websites wie diese erstellen müssen, denkt man oft darüber nach, welche Datenbank verwendet werden soll. Inhalte in einer Datenbank zu speichern, ist eine seit langem bewährte gute Idee. Aber es ist nicht der einzige Ansatz! SSGs können eine großartige Alternative sein, weil…

Sie sind günstig und einfach zu implementieren. SSGs sind in der Regel kostenlos, was sie großartig für ein MVP oder ein Proof of Concept macht.
Sie haben eine hohe Sicherheit. Es gibt nichts, was über den Browser gehackt werden kann, da alles, was die Website enthält, oft nur statische Dateien sind.
Sie sind bereit für die Skalierung. Der Host, bei dem Sie bereits sind, kann dies bewältigen.

Es gibt noch einen weiteren Vorteil für uns, wenn es um eine Inhalts-Website geht. Der Inhalt der Website selbst kann in statischen Dateien direkt im Repository geschrieben werden. Das bedeutet, dass das Hinzufügen und Aktualisieren von Inhalten direkt über Pull-Requests auf GitHub erfolgen kann, zum Beispiel. Selbst für technisch weniger versierte Personen öffnet dies die Tür zu Dingen wie Netlify CMS und dem Konzept des Open Authoring, was Community-Beiträge ermöglicht.

Aber lassen Sie uns den super einfachen Weg gehen und die Idee von Pull-Requests für Inhalte annehmen, indem wir nichts weiter als grundlegendes HTML verwenden.

Die Herausforderung

Wie Leute zum Hinzufügen oder Aktualisieren einer Ressource beitragen, ist nicht immer perfekt einfach. Leute müssen verstehen, wie sie Ihr Repository forken, wie und wo sie ihre Inhalte hinzufügen, welche Formatierungsstandards für Inhalte gelten, welche Felder erforderlich sind und all diese Dinge. Sie müssen die Website möglicherweise sogar selbst lokal „hochfahren“, um sicherzustellen, dass der Inhalt richtig aussieht.

Leute, die ernsthaft helfen wollen, ziehen sich manchmal zurück, weil der Prozess der Beitragsleistung eine technologische Hürde und eine Lernkurve darstellt – was schade ist.

Weißt du, was jeder tun kann? Ein `<form>` benutzen

Genau wie bei einer normalen Website ist der einfachste Weg für Leute, Inhalte einzureichen, das Ausfüllen eines Formulars und das Absenden mit den gewünschten Inhalten.

Was wäre, wenn wir eine Möglichkeit schaffen könnten, dass Benutzer Inhalte auf unseren Websites beisteuern können, indem sie nichts weiter als ein HTML-<form> verwenden, das so gestaltet ist, dass es genau die benötigten Inhalte aufnimmt? Aber anstatt dass das Formular in eine Datenbank postet, nimmt es den Weg eines Pull-Requests gegen unseren statischen Site-Generator? Da gibt es einen Trick!

Der Trick: Einen GitHub Pull-Request mit Query-Parametern erstellen

Hier ist ein kleiner, kaum bekannter Trick: Wir können einen Pull-Request gegen unser Repository vorab ausfüllen, indem wir Query-Parameter zu einer speziellen GitHub-URL hinzufügen. Das kommt direkt aus den GitHub-Dokumenten selbst.

Lassen Sie uns das rückwärts analysieren.

Wenn wir wissen, dass wir einen Link vorab ausfüllen können, dann müssen wir den Link generieren. Wir versuchen, dies einfach zu machen. Um diese dynamisch mit Daten gefüllte Verknüpfung zu generieren, verwenden wir einen Hauch von JavaScript.

Wie generieren wir also diesen Link, nachdem der Benutzer das Formular abgeschickt hat?

Demo!

Nehmen wir als Beispiel die Serverless Site von CSS-Tricks. Derzeit ist der einzige Weg, eine neue Ressource hinzuzufügen, das Repository auf GitHub zu forken und eine neue Markdown-Datei hinzuzufügen. Aber sehen wir uns an, wie wir das stattdessen mit einem Formular tun können, ohne diese Hürden zu überwinden.

Die Serverless Site selbst hat viele Kategorien (z.B. für Formulare), zu denen wir beitragen können. Der Einfachheit halber konzentrieren wir uns auf die Kategorie „Resources“. Leute können von dort Artikel über Dinge hinzufügen, die mit Serverless oder Jamstack zu tun haben.

The Resources page of the CSS-Tricks Serverless site. The site is primarily purple in varying shades with accents of orange. The page shows a couple of serverless resources in the main area and a list of categories in the right sidebar.

Alle Ressourcendateien befinden sich in diesem Ordner im Repository.

Showing the main page of the CSS-Tricks Serverless repo in GitHub, displaying all the files.

Lassen Sie uns einfach eine zufällige Datei von dort nehmen, um die Struktur zu untersuchen…

---
title: "How to deploy a custom domain with the Amplify Console"
url: "https://read.acloud.guru/how-to-deploy-a-custom-domain-with-the-amplify-console-a884b6a3c0fc"
author: "Nader Dabit"
tags: ["hosting", "amplify"]
---

In this tutorial, we’ll learn how to add a custom domain to an Amplify Console deployment in just a couple of minutes.

Wenn wir uns diesen Inhalt ansehen, muss unser Formular diese Spalten haben

Titel
URL
Autor
Tags
Snippet oder Beschreibung des Links.

Bauen wir also ein HTML-Formular für all diese Felder

<div class="columns container my-2">
  <div class="column is-half is-offset-one-quarter">
  <h1 class="title">Contribute to Serverless Resources</h1>

  <div class="field">
    <label class="label" for="title">Title</label>
    <div class="control">
      <input id="title" name="title" class="input" type="text">
    </div>
  </div>
  
  <div class="field">
    <label class="label" for="url">URL</label>
    <div class="control">
      <input id="url" name="url" class="input" type="url">
    </div>
  </div>
    
  <div class="field">
    <label class="label" for="author">Author</label>
    <div class="control">
      <input id="author" class="input" type="text" name="author">
    </div>
  </div>
  
  <div class="field">
    <label class="label" for="tags">Tags (comma separated)</label>
    <div class="control">
      <input id="tags" class="input" type="text" name="tags">
    </div>
  </div>
    
  <div class="field">
    <label class="label" for="description">Description</label>
    <div class="control">
      <textarea id="description" class="textarea" name="description"></textarea>
    </div>
  </div>
  
   <!-- Prepare the JavaScript function for later -->
  <div class="control">
    <button onclick="validateSubmission();" class="button is-link is-fullwidth">Submit</button>
  </div>
    
  </div>
</div>

Ich verwende Bulma für das Styling, daher stammen die hier verwendeten Klassennamen von dort.

Nun schreiben wir eine JavaScript-Funktion, die die Eingabe eines Benutzers in eine benutzerfreundliche URL umwandelt, die wir als GitHub-Query-Parameter für unseren Pull-Request verwenden können. Hier ist der Schritt für Schritt

Holen Sie sich die Eingabe des Benutzers bezüglich der Inhalte, die er hinzufügen möchte
Generieren Sie eine Zeichenkette aus all diesen Inhalten
Kodieren Sie die Zeichenkette, um sie so zu formatieren, dass Menschen sie lesen können
Hängen Sie die kodierte Zeichenkette an eine vollständige URL an, die auf die Seite von GitHub für neue Pull-Requests verweist

Hier ist der Pen

Nachdem der Submit-Button gedrückt wurde, wird der Benutzer direkt zu GitHub weitergeleitet, wo ein Pull-Request für diese neue Datei am richtigen Ort geöffnet ist.

GitHub pull request screen showing a new file with content.

Kurzer Vorbehalt: Benutzer benötigen immer noch ein GitHub-Konto, um beizutragen. Aber das ist immer noch viel einfacher, als zu wissen, wie man ein Repository forkt und einen Pull-Request aus diesem Fork erstellt.

Weitere Vorteile dieses Ansatzes

Nun, zum einen ist dies ein Formular, das auf unserer Website lebt. Wir können es beliebig stylen. Eine solche Kontrolle zu haben, ist immer schön.

Zweitens, da wir das JavaScript bereits geschrieben haben, können wir die gleiche grundlegende Idee verwenden, um mit anderen Diensten oder APIs zu kommunizieren, um die Eingabe zuerst zu verarbeiten. Wenn wir zum Beispiel Informationen von einer Website benötigen (wie den Titel, die Meta-Beschreibung oder das Favicon), können wir diese Informationen abrufen, indem wir einfach die URL angeben.

Dinge weiterführen

Spielen wir mit dem zweiten Punkt oben herum. Wir könnten unser Formular einfach vorab ausfüllen, indem wir Informationen von der vom Benutzer bereitgestellten URL abrufen, anstatt sie von Hand eingeben zu lassen.

In diesem Sinne fragen wir den Benutzer nun nur noch nach zwei Eingaben (anstatt vier) – nur der URL und den Tags.

Wie funktioniert das? Wir können Metadaten mit JavaScript von einer Website fetchen, indem wir einfach die URL haben. Es gibt viele APIs, die Informationen von einer Website abrufen, aber Sie könnten diejenige verwenden, die ich für dieses Projekt erstellt habe. Versuchen Sie, eine URL wie diese aufzurufen

https://metadata-api.vercel.app/api?url=https://css-tricks.de

Die obige Demo verwendet dies als API, um Daten basierend auf der vom Benutzer bereitgestellten URL vorab auszufüllen. Einfacher für den Benutzer!

Zusammenfassung

Sie könnten dies als ein sehr minimales CMS für jede Art von statischem Site-Generator betrachten. Alles, was Sie tun müssen, ist, das Formular anzupassen und die vorab ausgefüllten Query-Parameter zu aktualisieren, um den benötigten Datenformaten zu entsprechen.

Wie werden Sie diese Art von Dingen nutzen? Die vier Websites, die wir ganz am Anfang gesehen haben, sind gute Beispiele. Aber es gibt so viele andere Fälle, in denen Sie möglicherweise etwas mit einer Benutzereingabe tun müssen, und dies könnte eine einfache Möglichkeit sein, dies zu tun.