keystone ssg

Warnung

Keystone scheint heutzutage veraltet zu sein. Ich würde Ihnen stattdessen empfehlen, einen Blick auf Astro oder Vite zu werfen.

---

Warum Keystone?

Keystone ist ein Generator für statische Websites, der sich ideal zum schnellen Erstellen kleiner Websites eignet. Es ist keine Einrichtung erforderlich und eine Reihe praktischer Funktionen ist standardmäßig aktiviert.

Merkmale

• Einfache Installation und Einrichtung, ein Befehl und schon kann es losgehen
• Entwicklungsserver mit automatischer Aktualisierung
• Verwenden Sie Vorlagen und wiederverwendbare Teildateien/Importe mit Slots
• Automatisches Routing, einfach /public hochladen und schon kann es losgehen
• Babel-, SCSS- und Markdown-Unterstützung standardmäßig aktiviert, Quellkarten im Entwicklungsmodus
• JS- und CSS-Minimierung und Bündelung (mit Rollup)
• Dynamisches Laden von Links (kein erneutes Laden der Seite)
• Suchindexdateigenerator für eine einfache Website-Suche

Erste Schritte

Installieren

Erstellen Sie ein neues Verzeichnis und führen Sie den folgenden Befehl aus, um Keystone, package.json und git einzurichten. Knoten 14.xx erforderlich.

 $  npm install keystone-ssg

Großartig, Sie sind installiert!

Entwicklungsserver

Starten Sie den Keystone-Entwicklungsserver und gehen Sie dann zu http://localhost:8080, um die Beispielwebsite anzuzeigen.

 $ npm run dev

Projekt erstellen

Das Projekt wird nach der Ausführung des Befehls im Ordner /public erstellt und ist bereit zum Hochladen.

 $ npm run build

Erstellen Sie Ihre Website

Innerhalb eines Keystone-Projekts gibt es sechs wichtige Verzeichnisse, von denen jedes seinen eigenen Zweck hat:

Seiten

Jede HTML .html und Markdown- .md Datei im Seitenordner entspricht einer Seite auf Ihrer Website. Das Beispielprojekt hier enthält zwei Dateien. Versuchen Sie, index.html zu öffnen. Das automatische Routing bündelt die Dateien beim Ausführen von npm run build wie folgt im Ordner /public :

 /pages/index.html   ->  /public/index.html
/pages/example.md ->  /public/example/index.html

Möglicherweise ist Ihnen aufgefallen, dass index.html das folgende Tag hat: <_template basic.html /> . Dadurch wird der Inhalt von index.html in die Slotted-Vorlagendatei unter /templates/basic.html eingefügt. Dieses benutzerdefinierte HTML-Tag-Format funktioniert auch in .md Dateien.

Vorlagen

Vorlagen können mit /pages verwendet werden, um einen vorgefertigten Rahmen für Ihre Seiten bereitzustellen. Verwenden Sie ein <_slot /> -Tag in der Vorlagendatei, um einen Einstiegspunkt für Ihren Inhalt bereitzustellen. Öffnen Sie /templates/basic.html und suchen Sie nach:

 < _var title default="Keystone default title" />

Dies ist ein Variablenslot mit dem Namen title in einer Vorlagendatei mit einem optionalen Standardwert.

Wenn Sie Folgendes als Vorlagen-Tag in /pages verwenden, können Sie von einer Inhaltsseite aus einen benutzerdefinierten Wert in die Vorlage eingeben:

 < _template basic.html title="A custom title" /> 

Komponenten

Der Ordner /components wird einfach für wiederverwendbare Komponenten verwendet. Das <_import> -Tag wird zum Importieren von Komponenten in andere HTML-Dateien verwendet. Ein Beispiel hierfür befindet sich in /templates/basic.html .

 < _import header.html />

Das <_import> -Tag kann auch verwendet werden, um den Inhalt jeder anderen Art von Datei (JS, SCSS usw.) zu importieren, nachdem die Quelle zunächst gebündelt wurde.

Src

Platzieren Sie Javascript-Dateien im Ordner /src . Das folgende Tag wird in ein reguläres <script> -Importtag umgewandelt und mit Ihrer Datei /src/main.js verknüpft:

 < _script main.js />

ES6-Importe werden vollständig unterstützt und die resultierende Datei wird mit Babel transpiliert, mit Rollup gebündelt und minimiert.

Stile

Der Ordner /styles wird für Ihr CSS/SCSS verwendet. Das folgende Tag wird in ein reguläres <link> CSS-Import-Tag umgewandelt, das auf Ihre kompilierte Datei /styles/main.scss verweist:

 < _style main.scss />

Alle node-sass Funktionen werden vollständig unterstützt, einschließlich @import .

Vermögenswerte

Hier werden statische Assets platziert, also Schriftarten, Bilder, Icons. Alles hier wird in den entsprechenden Ordner im Stammverzeichnis übertragen, zum Beispiel:

 /assets/favicon.ico -> /public/favicon.ico
/assets/fonts/fontname.ttf -> /public/fonts/fontname.ttf

Notizen

Keystone-HTML-Tags

• Jedes benutzerdefinierte Keystone-HTML-Tag kann überall in einer HTML-Datei verwendet werden, sogar innerhalb anderer HTML-Attribute, außer in anderen Keystone-Tags.
• Für alle benutzerdefinierten Keystone-Tags können Sie alternativ ein src-Attribut verwenden, um eine Datei in einem beliebigen Ordner anzusprechen: <_template src='myfolder/myfile.html' /> .
• Alle Pfade beziehen sich auf den Ordner, package.json enthält. Verwenden Sie keinen Schrägstrich am Anfang, es sei denn, Sie möchten auf eine Datei außerhalb des Projekts zugreifen.
• Keystone-HTML-Tag-Attribute können „einfache“, „doppelte“ oder „Backtick“-Anführungszeichen verwenden.

Dynamisches Laden

• Beim dynamischen Laden wird der Link zur lokalen Website abgerufen und der Inhalt der aktuellen Seite durch die neue Seite ersetzt, ohne dass die Seite neu geladen und gewechselt werden muss.
• Während das dynamische Laden aktiviert ist, wird der Seitenstatus (z. B. Eingabewerte, Scrollposition) bei Verwendung der Zurück-Schaltfläche nicht gespeichert.
• Wenn auf einen Link geklickt wird, wird die Klasse .keystone-page-loading auf display: block gesetzt. Wenn die Klasse im CSS auf display: none eingestellt ist, kann damit ein Ladeindikator erstellt werden.
• Deaktivieren Sie das dynamische Laden in keystone.config.js.

Suchindexgenerator

• Der Suchindexgenerator generiert eine Datei, search.json , im Stammverzeichnis. Dabei handelt es sich um ein JSON-Array, das ein Objekt für jede Seite enthält und den Textinhalt, den Titel und den Pfad der Seite auflistet.
• Alle HTML-Tags werden von der Seite entfernt und nur der Text bleibt erhalten und gespeichert.
• Diese Datei kann über eine Website-Suchfunktion abgerufen und abgefragt werden, um leicht herauszufinden, welche Seite welchen Inhalt enthält.
• Deaktivieren Sie den Suchleisten-Helfer in keystone.config.js.

Verschiedenes

• Der public Ordner wird von Git ignoriert. Entfernen Sie die public Zeile aus .gitignore falls Sie sie zum Festschreiben an Git verwenden möchten.

Keystone wird aktualisiert

• Ersetzen Sie die Versionsnummer in package.json durch die Version, auf die Sie aktualisieren, und führen Sie npm install keystone-ssg aus, um ein schnelles Upgrade durchzuführen.

API

Schlagworte

Etikett	Beschreibung	Attribute
<_template>	Importiert die aktuelle Datei in einen <_slot> innerhalb der Vorlagendatei	[Dateiname], [Variablenname], Quelle
<_slot>	Wird innerhalb einer Vorlagendatei als Einstiegspunkt für die importierte Datei verwendet	Keiner
<_var>	Wird in einer Vorlagendatei verwendet und durch eine Variable aus <_template> ersetzt	[Variablenname], Standard
<_import>	Importiert eine Komponente	[Dateiname], src
<_script>	Erstellt ein <script> -Tag, das auf das gebündelte Skript verweist	[Dateiname], src
<_style>	Erstellt ein <link> -Tag, das auf die gebündelte CSS-Datei verweist	[Dateiname], src

NPM-Befehle

Befehl	Beschreibung	Ausgabeunterschiede
npm run dev	Erstellt die Website für die Entwicklung und startet dann den Keystone-Entwicklungsserver.	Es werden Inline-Quellkarten generiert. Das Skript des Entwicklungsservers wird eingefügt.
npm run build	Erstellt die Website für die Produktion.	Das Bündel ist komprimiert und minimiert.

Konfigurationsdatei

Die Konfigurationsdatei ist keystone.config.js

Option	Beschreibung	Standard
dynamische Links	Ermöglicht dynamisch geladene lokale Links auf Ihrer Keystone-Website, keine Aktualisierung erforderlich	WAHR
Suchdatei	Erzeugt search.json im Stammverzeichnis	WAHR
indexPath	Das Stammverzeichnis Ihrer Website	'/'
Hafen	Der Entwicklungsserver-Port, localhost: 8080	8080
portWs	Ein zweiter Port, der für den Entwicklungsserver verwendet wird	8081
devServerIp	Der Standort des Entwicklungsservers, localhost :8080. Ersetzen Sie diese durch die lokale IP Ihres Geräts, um den Entwicklungsserver auf lokalen Geräten anzuzeigen (Beispiel: „192.168.1.103“).	'localhost'
beobachtet	Die vom Keystone-Entwicklungsserver überwachten Verzeichnisse, die eine Neukompilierung und Seitenaktualisierung erzwingen, wenn Dateien bearbeitet werden	['templates', 'pages', 'assets', 'components', 'src', 'styles']
bauen	Das Inhaltsseitenverzeichnis	'Seiten'
serviert	Das Verzeichnis, das die generierte Website enthält	'öffentlich'
vollständigNeukompilieren	Erzwingen Sie eine vollständige Neukompilierung aller Dateien nach jeder Dateiänderung im Entwicklungsmodus	FALSCH

Standardverzeichnislayout

 | empty-keystone-project
--| .git/
--| assets/
--| components/
--| pages/
--| src/
--| styles/
--| templates/
--| keystone.config.js
--| package.json
--| package-lock.json

Plugin-Fehler

Wenn nach der Installation und Ausführung des Beispiels ein PLUGIN_ERROR auftritt, handelt es sich hierbei um ein Babel-Problem. Führen Sie den folgenden Befehl aus, um das Problem zu beheben:

 npm install @babel/core @babel/preset-env --save-dev