Eine gemeinschaftsgesteuerte Website mit Eleventy: Vorbereitung auf Beiträge

Ich habe in letzter Zeit über alle anderen Tools hinaus zu Eleventy (auch bekannt als 11ty) gegriffen, wenn ich eine Website entwickeln möchte. Es ist schwer, einen statischen Seitengenerator zu schlagen, der fortgeschrittene Templating-Möglichkeiten bietet, während er sich ansonsten zurückhält und es Ihnen erlaubt, einfach nur zu erschaffen.

Eine dieser Websites ist Style Stage, eine moderne CSS-Showcase, die durch Beiträge aus der Community gestaltet wird. Eleventy war für dieses gemeinschaftsgesteuerte Projekt in mehrfacher Hinsicht perfekt:

• Seine außergewöhnlich schnellen Builds lokal und auf einem Produktionshost
• Es ist kompromisslos, wie Vorlagen erstellt werden
• Seine Fähigkeit, jeden Dateityp mit vollständiger Kontrolle darüber, wie und wo Dateien gerendert werden, zu erstellen
• Seine Fähigkeit, Vorlagensprachen wie HTML, Markdown und Nunjucks zu vermischen
• Es ist hoch performant, da es zu statischem HTML kompiliert wird, ohne dass für die Produktion erforderliche Abhängigkeiten notwendig sind

Der wichtigste Grund, warum Eleventy eine großartige Wahl für die Erstellung einer gemeinschaftsgesteuerten Website ist, ist die Möglichkeit, dynamisch Seitenseiten aus Datenquellen zu erstellen. Wir werden uns ansehen, wie Sie diese Funktion und mehr nutzen können, wenn wir unsere Beispiel-Community-Website erstellen.

Was gehört zur Erstellung einer gemeinschaftsgesteuerten Website?

In der nicht allzu fernen Vergangenheit konnte die Erstellung einer gemeinschaftsgesteuerten Website potenziell ein schmerzhafter Prozess sein, der CMS-Alpträume mit der Erstellung von Beitrags-Workflows beinhaltete. Mit Eleventy und einigen anderen modernen Tools ist dies nun fast vollständig automatisierbar mit minimaler Aufsicht.

Bevor wir dazu kommen, Beiträge einzuladen, haben wir selbst noch etwas Arbeit zu tun.

1. Bestimmen Sie, welche Inhalte Beitragende ändern dürfen

Dies wird viele der anderen Entscheidungen leiten. Im Fall von Eleventy für Style Stage habe ich eine JSON-Datei erstellt, die Beitragende verwenden können, um Pull-Anfragen zum Ändern und Bereitstellen ihrer eigenen relevanten Metadaten zu erstellen, die zur Erstellung ihrer Seiten verwendet werden.

Vielleicht möchten Sie auch den Zugriff auf zusätzliche Assets ermöglichen, oder es macht Sinn, mehrere Datendateien für die einfache Kategorisierung und Abfrage von Daten zu haben. Oder vielleicht können Beitragende Markdown-Dateien in einem bestimmten Verzeichnis hinzufügen.

Berücksichtigen Sie den Umfang dessen, was Beitragende ändern oder einreichen können, und wägen Sie dies gegen eine Schätzung Ihrer Verfügbarkeit zur Überprüfung von Einreichungen ab. Dies wird zu einer erfolgreichen und überschaubaren Community beitragen.

GitHub Actions kann es ermöglichen, eine Pull-Anfrage mit ungültigen Dateien zu kennzeichnen oder zu schließen, wenn Sie eine erweiterte automatisierte Überprüfung eingehender Inhalte benötigen.

2. Erstellen Sie Richtlinien für Beitragende

Wenn Sie im Voraus Zeit investieren, um Ihre Richtlinien zu durchdenken, kann dies zu Ihrem Gesamtplan beitragen. Möglicherweise identifizieren Sie zusätzliche benötigte Funktionen oder Elemente, die automatisiert werden können.

Sobald Ihre Richtlinien vorbereitet sind, ist es am besten, sie in einer speziellen Datei in Ihrem GitHub-Repository namens CONTRIBUTING.md aufzunehmen. Der Dateiname in Großbuchstaben ist das erwartete Format. Diese Datei erstellt einen zusätzlichen automatischen Link für Beitragende, wenn sie ihre Pull-Anfragen oder Issues erstellen, in denen sie aufgefordert werden, sicherzustellen, dass sie die Richtlinien überprüft haben.

Wie mit Lizenzierung und Urheberschaft von Inhalten umzugehen ist, gehört ebenfalls in diese Kategorie. Zum Beispiel veröffentlicht Style Stage beigesteuerte Stylesheets unter der CC BY-NC-SA-Lizenz, aber Autoren behalten das Urheberrecht an Originalgrafiken. Als Teil des Build-Prozesses werden die Lizenz und die Autorenattribution den Stilen angehängt, und die Metadaten der Autorenattribution werden innerhalb der Style-Seiten-Vorlage aktualisiert.

Sie möchten auch Richtlinien bezüglich akzeptabler Inhalte berücksichtigen und was dazu führen würde, dass Einreichungen abgelehnt werden. Style Stage gibt an, dass

Einreichungen werden abgelehnt, wenn sie obszöne, übermäßig gewalttätige oder anderweitig geschmacklose Bilder verwenden, gegen die oben genannten Richtlinien verstoßen oder aus anderen Gründen nach Ermessen des Maintainers.

3. Workflow und Automatisierungen vorbereiten

Während Eleventy den Website-Build übernimmt, sind die anderen wichtigen Akteure, die Style Stage-Beiträge ermöglichen, Netlify und GitHub.

Beitragende reichen eine Pull-Anfrage beim Style Stage-Repo auf GitHub ein, und wenn sie das tun, erstellt Netlify eine Deploy-Vorschau. Dies ermöglicht es Beitragenden, zu überprüfen, ob ihre Einreichung wie erwartet funktioniert, und spart mir als Maintainer Zeit, indem ich Einreichungen nicht herunterladen muss, um sicherzustellen, dass sie den Richtlinien entsprechen.

Die gesamte Diskussion findet über GitHub statt. Dies hat den zusätzlichen Vorteil der öffentlichen Rechenschaftspflicht, die hilft, böswillige Akteure abzuschrecken.

Wenn der Beitragende eine Änderung vornehmen muss, kann er seine Pull-Anfrage aktualisieren oder eine erneute Bereitstellung der Branch-Vorschau anfordern, wenn es sich um einen Remote-Asset handelt, der sich geändert hat. Diese erneute Bereitstellung ist ein sehr kleiner manueller Schritt, und sie ist möglicherweise nicht für jede PR erforderlich – oder überhaupt nicht, je nachdem, wie Sie Beiträge akzeptieren.

Der letzte Schritt ist die endgültige Genehmigung der PR und das Mergen in den Haupt-Branch. Sobald die Pull-Anfrage gemerged ist, stellt Netlify die Änderungen sofort in der Produktion bereit.

Eleventy ist natürlich ein statischer Seitengenerator, und mehrere Hoster bieten Webhooks an, um einen Build auszulösen. Netlify's Build Plugins sind ein gutes Beispiel dafür. Aber wenn Sie Daten häufiger als bei jedem Merge einer PR aktualisieren müssen, ist eine Option die Verwendung von IFTTT oder Zapier, um tägliche Deploys einzurichten, oder Deploys basierend auf einer Vielzahl anderer Trigger.

Es ist erwähnenswert, dass das, worüber wir hier sprechen, Ihre Beitrags-Zielgruppe auf Personen mit einem GitHub-Konto beschränkt. Allerdings können GitHub-Beiträge vollständig über die Weboberfläche erfolgen, sodass es sehr gut möglich ist, Anleitungen bereitzustellen, damit andere Benutzer – auch solche, die nicht programmieren – trotzdem teilnehmen können.

4. Wählen Sie eine Methode für Beitrags- und Community-Updates

Die erste Überlegung hier ist zu entscheiden, wie kritisch es für Beitragende ist, über Updates auf Ihrer Website informiert zu werden, indem die wahrscheinlichen Auswirkungen der Änderung bewertet werden.

Im Fall von Style Stage wird der Kern unverändert bleiben, aber es gibt geplante optionale Funktionalitäten. Ich habe mich für einen wöchentlichen (-ish) Newsletter entschieden. So können sich die Leute dafür anmelden, und es gibt einen Mehrwert für Beitragende und Benutzer gleichermaßen.

Matthew Ströms „Verwendung von Netlify Forms und Netlify Functions zum Erstellen eines E-Mail-Anmelde-Widgets“ ist ein großartiger Ort, um zu lernen, wie Sie Abonnenten mit einem statischen Formular in Eleventy zu Ihrem Newsletter hinzufügen können. Es behandelt auch eine Funktion zum Senden der E-Mail des Abonnenten an Buttondown, einen schlanken E-Mail-Dienst. Als Beispiel, wie Sie Ihre Buttondown-E-Mail-Vorlage und -Inhalte in Eleventy verwalten können, sehen Sie sich die Style Stage-Einrichtung an, die zeigt, wie der Newsletter vom veröffentlichten Website-Build ausgeschlossen wird.

Wenn Sie nur Updates mit niedriger Priorität erwarten, dann reichen die Repository-Benachrichtigungen von GitHub für die Kommunikation aus. Das Erstellen von Releases ist eine weitere Möglichkeit. Oder, hey, es ist sogar möglich, Benachrichtigungen auf der Website selbst zu integrieren.

5. Potenzielle Beitragende finden und einbeziehen

Style Stage war eine Idee, die ich durch eine Umfrage auf Twitter ausgekundschaftet habe. Dann habe ich einen „Aufruf an Beitragende“ gestartet und mit den Antwortenden sowie denen, die mich retweetet haben, interagiert. Eine kurze Frist half auch, motivierte Beitragende zu finden, die Style Stage halfen, ohne Einreichungen zu starten. Viele dieser Beitragenden wurden zu Evangelisten, die Style Stage noch mehr Leuten vorstellten. Ich habe auch einen Launch-Livestream beworben, der als Werbematerial diente.

Das ist es, was es bedeutet, mit Beitragenden zu „interagieren“. Wege zur Interaktion zu schaffen und mit ihnen in Kontakt zu bleiben, hilft, gelegentliche Beitragende in „Fans“ zu verwandeln, die andere zur Teilnahme ermutigen.

Denken Sie daran, dass der Website-Inhalt ein großartiger Ort ist, um zur Teilnahme zu ermutigen! Style Stage widmet seine gesamte Seite der Ermutigung zu Einreichungen. Wenn das für Sie nicht möglich ist, könnten Sie in Erwägung ziehen, wo es sinnvoll ist, Aufforderungen für Beiträge zu verwenden.

6. Repository-Einstellungen finalisieren und Community-Health-Dateien einfügen

Stellen Sie abschließend sicher, dass Ihr Repository öffentlich zugänglich ist und die zutreffenden „Community-Health“-Dateien enthält. Dies sind Dokumente, die Richtlinien festlegen, gute Erwartungen an Community-Mitglieder setzen, einen Verhaltenskodex definieren und andere Informationen bereitstellen, die zur allgemeinen „Gesundheit“ der Community beitragen. In der GitHub-Dokumentation finden Sie eine Reihe von Beispielen, Vorschlägen und Tipps, wie Sie dies tun können.

Während die Dokumentation ein halbes Dutzend Dateien erwähnt, sind meiner bisherigen Erfahrung nach die drei Dateien, die Sie mindestens benötigen,

• eine README.md-Datei am Stammverzeichnis des Projekts, die den Projektnamen und eine gute Beschreibung dessen, was es ist, enthält. GitHub zeigt den Inhalt unter der Liste der Dateien im Repository an.
• eine CONTRIBUTING.md-Datei, die den Einreichungsprozess für Beiträge beschreibt. Seien Sie explizit, was die Schritte angeht und was eine „gute“ Einreichung ausmacht.
• eine Pull-Request-Vorlage. Ich würde das nicht gerade als obligatorisch bezeichnen, aber es lohnt sich, es in diese Liste aufzunehmen, da es die Erwartungen für die Einreichung von Beiträgen weiter festigt. Viele Vorlagen enthalten sogar eine Checkliste, die die Anforderungen für die Genehmigung detailliert beschreibt.

Oh, und die Einrichtung einer Branch-Schutzregel für den Haupt-Branch ist ebenfalls eine gute Idee. Sie können dies tun, indem Sie in den Repository-Einstellungen zu Settings → Branches gehen und die Option „Add rule“ auswählen. „Require pull request reviews before merging“ und „Require review from Code Owners“ sind die beiden wichtigsten Einstellungen, die Sie aktivieren sollten. Sie können die GitHub-Dokumentation konsultieren, um mehr über diesen Schutz zu erfahren.

Als Nächstes…

Was wir hier behandelt haben, ist ein Ausgangspunkt für die Erstellung einer gemeinschaftsgesteuerten Website mit Eleventy. Der Punkt ist, dass es mehrere Dinge zu beachten gibt, bevor wir direkt zum Code übergehen. Communities brauchen Pflege, und das erfordert einige Schritte, die dazu beitragen, eine engagierte und gesunde Community aufzubauen.

Sie sind wahrscheinlich schon ungeduldig, eine Community-Website mit Eleventy zu coden! Nun, das kommt im nächsten Teil dieser zweiteiligen Serie.  Gemeinsam entwickeln wir einen Eleventy-Starter von Grund auf, den Sie für Ihre eigene Community- (oder persönliche) Website erweitern können.