stacy
v2.0.0
Stacy ist ein Website-Generator, der Inhalte von Contentful CMS mit Handlers-Vorlagen kombiniert, um die Website-Seiten zu erstellen.
Stacy gleicht die Eintragsinhaltstypen von Contentful in einer Eins-zu-eins-Beziehung mit den Steering-Vorlagen in Ihrem Website-Projekt ab – es gibt eine Vorlage für jeden Eintragstyp, der in Ihrem Inhaltsmodell definiert ist. Aus Stacys Sicht gibt es zwei Arten von Einträgen: Seiteneinträge und Moduleinträge . Ein Seiteneintrag erzeugt in Kombination mit seiner Vorlage eine einzelne Website-Seite mit einer eindeutigen URL. Moduleinträge können mithilfe der Referenzfelder von Contentful in Seiten und andere Module eingefügt werden, um wiederverwendbare Inhalte zu erstellen oder einfach um Inhalte und Vorlagen durch Aufteilen in kleinere Teile zu strukturieren.
Was Stacy von vielen bestehenden statischen Website-Generatoren unterscheidet, besteht darin, dass es die automatische Veröffentlichung der Website in einem S3-Bucket in der Amazon Cloud unterstützt, von wo aus sie im Internet bereitgestellt werden kann. Stacy stellt eine spezielle Infrastruktur in der Amazon Cloud bereit, die über ihre Webhooks-Funktionalität mit Contentful verbunden werden kann. Wenn Inhalte in Ihrem Contentful-Bereich aktualisiert werden, wird die von Stacy in Amazon Cloud bereitgestellte Infrastruktur Ihrer Website benachrichtigt und generiert automatisch nur die Seiten Ihrer Website neu und veröffentlicht sie erneut, die von der Aktualisierung betroffen sind. Es ist keine manuelle Neugenerierung und erneute Bereitstellung der Website erforderlich.
Wenn Sie Stacy verwenden, handelt es sich bei Ihrer Website um ein NPM-Projekt, das normalerweise zur Versionskontrolle in einem Git-Repository überprüft wird. Das Projekt umfasst Ihre Lenkervorlagen und statischen Inhalt (wie CSS-Stylesheets, im Website-Design verwendete Bilder, Schriftarten usw.), während sich der Website-Inhalt im Contentful-Bereich befindet. Beim Website-Projekt verwenden die Website-Entwickler das Stacy-Befehlszeilentool, um die Website zu entwickeln, zu veröffentlichen und erneut zu veröffentlichen. Sobald die Website in Amazon Cloud veröffentlicht ist, arbeiten die Inhaltsautoren nur noch mit Contentful UI.
Eine ausführliche Anleitung/Komplettlösung finden Sie unter Erstellen einer Website mit Stacy.
Zunächst benötigen Sie einen Contentful-Bereich für den Inhalt Ihrer Website. Sobald Sie das haben, können Sie ein neues Projekt für Ihre Website erstellen.
Stellen Sie sicher, dass Sie Node.js Version 10.16.3 oder neuer zusammen mit npm installiert haben. Wenn Sie die Website in der Amazon Cloud veröffentlichen möchten, muss auch AWS CLI installiert sein.
Beginnen Sie mit der globalen Installation von Stacy:
npm install -g stacy
Gehen Sie in Ihrem Contentful-Bereich zu Bereichseinstellungen→API-Schlüssel und fügen Sie unter Inhaltsbereitstellungs-/Vorschau-Tokens einen API-Schlüssel hinzu. Beachten Sie die Werte für Space-ID und Content Delivery API-Zugriffstoken , die Sie verwenden werden, um Ihre Stacy-Umgebung mit Ihrem Contentful-Space zu verbinden.
Jetzt können Sie ein erstes Projekt für Ihre Website erstellen:
stacy new --cf-space <your space ID> --cf-access-token <your access token> mywebsite
Dadurch wird im aktuellen Verzeichnis ein neues Projektverzeichnis mit dem Namen „mywebsite“ erstellt. Der Wert „mywebsite“ wird als Site-ID bezeichnet. Verwenden Sie einen anderen Wert, der Ihre Website identifiziert. Der Wert sollte URL-konform sein (Kleinbuchstaben, Ziffern und Bindestriche).
Platzieren Sie in Ihrem Projektverzeichnis statischen Inhalt unter /static (dieser wird unverändert auf Ihre Website kopiert) und legen Sie Ihre Eintragsvorlagen unter /templates ab. Der Name der Vorlagendatei (ohne Erweiterung) muss genau mit dem entsprechenden Eintragsinhaltstyp in Ihrem Contentful -Content-Modell übereinstimmen. Unter /templates können die Vorlagendateien in Unterordnern organisiert werden. Allerdings müssen die Dateinamen in allen Unterordnern eindeutig sein, da sie dazu dienen, Vorlagen eindeutig den Eintragsinhaltstypen zuzuordnen (Unterordner in /templates spielen keine Rolle).
Hinweis: Normalerweise erzeugt eine Vorlage in Kombination mit dem Inhalt eines Eintrags HTML. Wenn Sie eine andere Art von Inhalt erstellen müssen, können Sie dem Vorlagennamen eine Erweiterung hinzufügen. page.hbs erzeugt beispielsweise HTML. Um einfachen Text zu erzeugen, verwenden Sie page.txt.hbs . Dies bedeutet auch, dass page.hbs und page.html.hbs identisch sind.
Sie können Ihre Website jetzt zu Entwicklungszwecken lokal ausführen:
stacy serve
Sie können Ihre Website unter http://localhost:8080/ sehen. Nachdem Sie eine Vorlage, einen statischen Inhalt oder einen Inhalt in Contentful bearbeitet haben, laden Sie die Seite einfach neu.
Um den lokalen Webserver von Stacy zu stoppen, verwenden Sie Ctrl+C .
Führen Sie stacy --help aus, um andere verfügbare Befehle anzuzeigen.
Den Inhalt Ihres Projektverzeichnisses können Sie in ein Git-Repository wie GitHub oder Bitbucket einchecken.
In Ihren Vorlagen sind alle Eingabefelder über die Feld-ID verfügbar, die in Ihrem Inhaltsmodell definiert ist. Sie können sie direkt in Ihrer Vorlage referenzieren. Zum Beispiel:
Dadurch wird der Wert des caption des Eintrags ausgegeben. Beachten Sie, dass hier die Feld-ID und nicht der Feldname verwendet wird.
Stacy fügt ein paar spezielle Helfer hinzu, die Sie in Ihren Vorlagen verwenden können:
module <reference field> – Moduleintrag einschließen, auf den im Feld „Referenztyp“ verwiesen wird. Angenommen, Sie haben ein Feld mit ID paragraphs und es handelt sich um eine Referenzliste:
asset <asset field> – Fügen Sie das referenzierte Asset ein, z. B. ein Bild. Zum Beispiel:
Derzeit werden nur Bild-Assets unterstützt, für die ein HTML- <img> -Tag gerendert wird.
assetSrc <asset field> – URL des Assets abrufen. Zum Beispiel:
assetTitle <asset field> – Titel des Assets abrufen. Zum Beispiel:
markdown <long text field> – Markdown-Langtextfeld rendern. Zum Beispiel:
Beachten Sie die hier benötigten dreifachen Klammern, da der Helfer HTML generiert, das nicht maskiert werden muss.
richText <rich text field> – Rich-Text-Feld rendern. Zum Beispiel:
Beachten Sie wie bei markdown die dreifachen Klammern.
json <field> – Gibt die interne Contentful JSON-Darstellung des Felds aus. Zum Beispiel:
Dieser Helfer kann bei der Diagnose von Problemen hilfreich sein.
Wie oben erwähnt, besteht eine Eins-zu-eins-Beziehung zwischen den Inhaltstypen, die Sie im Inhaltsmodell und in den Vorlagen Ihres Contentful-Bereichs definieren.
Hinweis: Streng genommen können Sie mehr als eine Vorlage für einen bestimmten Inhaltstyp haben, um die Generierung verschiedener Dateitypen für denselben Inhaltseintrag zu ermöglichen. Für das Inhaltstyp-ID- module könnten Sie beispielsweise die Vorlagen module.html.hbs und module.xml.hbs verwenden. Die erste Vorlage erstellt eine HTML-Datei für den Eintrag und die zweite Vorlage erstellt eine XML-Datei.
Beachten Sie beim Definieren eines Inhaltstyps den API-Bezeichner (auch als Inhaltstyp-ID bezeichnet). Die Vorlagendatei für den Inhaltstyp muss denselben Namen (plus Erweiterung) haben.
Es gibt eine Anforderung für Inhaltstypen für Seiteneinträge (im Gegensatz zu Moduleinträgen): Ein Seiteninhaltstyp muss ein erforderliches Slug- Feld definieren. Der Wert im Feld bestimmt den Namen der generierten Datei, wenn der Inhaltseintrag mit der entsprechenden Vorlage kombiniert wird. Wenn der Slug-Wert für einen Seiteneintrag beispielsweise „index“ ist, lautet die generierte Seite „/index.html“. Wenn der Slug „more/terms“ lautet, lautet die Seite „/more/terms.html“. Und so weiter.
Standardmäßig muss die Feld-ID für das Slug-Feld slug lauten. Die ID kann in der stacy.json Datei des Projekts überschrieben werden. Abgesehen davon, dass das Slug-Feld in der Definition des Inhaltstyps erforderlich ist, wird auch empfohlen, ihm einen benutzerdefinierten Übereinstimmungsmustervalidator zuzuordnen, um das spezifische Format des Feldwerts sicherzustellen. Der reguläre Ausdruck für den Validator kann ^w[w-]*(/w[w-]*)*$ sein.
Wenn Sie bereit sind, Ihre Website in AWS bereitzustellen, müssen Sie zunächst die Stacy-Infrastruktur unter Ihrem AWS-Konto einrichten. Bevor Sie dies tun können, müssen Sie mehrere Schritte ausführen:
Erstellen Sie den Ziel-S3-Bucket. Hier wird Ihre Website veröffentlicht und von dort aus bereitgestellt (wahrscheinlich über CloudFront). Alternativ können Sie einen Bucket verwenden, den Sie bereits haben (Stacy unterstützt auch die Veröffentlichung in einem Unterordner im Ziel-Bucket).
Wenn Sie es noch nicht haben, erstellen Sie einen S3-Bucket, den Stacy zum Hochladen des Lambda-Funktionspakets des Herausgebers verwendet. Die Publisher-Lambda-Funktion ist der Teil, der auf Contentful -Veröffentlichungs- und Unpublish- Ereignisse reagiert und die relevanten Seiten und Assets im Ziel-S3-Bucket aktualisiert.
Erstellen Sie das Publisher-Paket:
stacy build-publisher
Dadurch wird das Publisher-Lambda-Funktionspaket in Ihrem Projekt unter /build/stacy-mywebsite-publisher.zip erstellt. Laden Sie diese Datei in Ihren Lambda Functions S3-Bucket hoch.
Stacys Befehl stacy new hat eine CloudFormation-Vorlage für die AWS-Umgebung generiert und in Ihrem Projekt unter /misc/cfn-template.json gespeichert. Sie können es überprüfen und bei Bedarf anpassen. Andernfalls erstellen Sie unter Ihrem AWS-Konto einen Stacy-Stack für Ihre Website.
Sobald der CloudFormation-Stack erstellt ist, müssen Sie die Richtlinie des Ziel-S3-Buckets anpassen, damit der Stacy-Publisher generierte Website-Inhalte darin veröffentlichen kann. Die Richtlinie des Buckets kann etwa Folgendes umfassen:
{
"Version" : " 2012-10-17 " ,
"Statement" : [
{
"Effect" : " Allow " ,
"Principal" : {
"AWS" : " <Stacy publisher role ARN> "
},
"Action" : [
" s3:PutObject " ,
" s3:DeleteObject "
],
"Resource" : " arn:aws:s3:::<bucket name>/* "
}
]
} Ersetzen Sie in der obigen Richtlinie den ARN der Stacy-Publisher-Rolle durch den Wert, den Sie im Ausgabeparameter PublisherRoleArn Ihres CloudFormation-Stacks finden, und den Bucket-Namen durch den Bucket-Namen der Zielwebsite (den Bucket, auf den die Richtlinie angewendet wird).
Jetzt müssen Sie Ihre Entwicklungsumgebung für die Veröffentlichung vorbereiten. Öffnen und bearbeiten Sie .env Datei in Ihrem Website-Projekt. Legen Sie darin alle AWS_* Variablen auf die richtigen Werte fest. Beachten Sie, dass Sie den Wert für die Variable AWS_PUBLISH_EVENT_SOURCE_MAPPING im Ausgabeparameter PublishEventSourceMappingId des CloudFormation-Stacks finden.
Sobald Ihre .env Datei korrekt eingerichtet ist, können Sie Ihre Website veröffentlichen mit:
stacy publish
Ein letzter Einrichtungsschritt besteht darin, einen Webhook in Ihrem Contentful-Bereich zu konfigurieren, um den Stacy-Publisher bei Veröffentlichungs- und Veröffentlichungsereignissen aufzurufen. Suchen Sie in Ihrem AWS-Konto im API Gateway-Service nach der von Stacy für Sie erstellten API. In der prod der API gibt es nur eine Methode POST /publish . Notieren Sie sich die Aufruf-URL .
Gehen Sie außerdem zum Abschnitt „API-Schlüssel“ und notieren Sie sich den Wert des für Stacy erstellten API-Schlüssels.
Gehen Sie in Ihrem Contentful-Bereich zu Space-Einstellungen→Webhooks und fügen Sie einen Webhook hinzu. Geben Sie die Aufruf-URL der API Gatwey in das URL-Feld ein (belassen Sie die Methode POST ). Wählen Sie dann im Abschnitt „Trigger“ die Option „Bestimmte auslösende Ereignisse auswählen“ . Aktivieren Sie die Kontrollkästchen „Veröffentlichen“ und „Veröffentlichung aufheben“ in den Zeilen „Eintrag“ und „Asset“ (insgesamt sind 4 Kontrollkästchen aktiviert).
Klicken Sie im Abschnitt „Header“ auf „Geheimen Header hinzufügen“ . Geben Sie „X-API-Key“ in das Feld „Key “ und in das Feld „Value“ den API-Schlüssel vom API Gateway ein.
Sobald Sie diesen Webhook speichern, wird durch das Veröffentlichen und Entfernen von Einträgen und Assets in Contentful der Herausgeber im AWS-Setup ausgelöst, und schon sind Sie startklar!
