keystone ssg

Avertissement

Keystone a l'air obsolète ces jours-ci, je vous recommande plutôt de jeter un œil à Astro ou Vite.

---

Pourquoi Keystone ?

Keystone est un générateur de sites statiques idéal pour créer rapidement de petits sites Web. Aucune configuration requise et un ensemble de fonctionnalités pratiques sont activées par défaut.

Caractéristiques

• Installation et configuration faciles, une seule commande et prêt à l'emploi
• Serveur de développement à actualisation automatique
• Utilisez des modèles et des partiels/importations réutilisables, avec des emplacements
• Routage automatique, téléchargez simplement /public et vous êtes prêt à partir
• Prise en charge de Babel, SCSS et Markdown activée par défaut, cartes sources en mode développement
• Minification et regroupement JS & CSS (avec Rollup)
• Chargement de lien dynamique (pas de rechargement de page)
• Générateur de fichiers d'index de recherche, pour une recherche facile sur le site Web

Commencer

Installer

Créez un nouveau répertoire et exécutez la commande suivante pour configurer Keystone, package.json et git. Nœud 14.xx requis.

 $  npm install keystone-ssg

Super, vous êtes installé !

Serveur de développement

Démarrez le serveur de développement Keystone, puis accédez à http://localhost:8080 pour voir l'exemple de site Web.

 $ npm run dev

Construire un projet

Le projet est construit dans le dossier /public après l'exécution de la commande, prêt à être téléchargé.

 $ npm run build

Construire votre site Web

Il existe six répertoires importants au sein d'un projet Keystone, chacun avec son propre objectif :

Pages

Chaque fichier HTML .html & markdown .md du dossier pages correspond à une page de votre site Web. Il y a deux fichiers dans l'exemple de projet ici, essayez d'ouvrir index.html . Le routage automatique regroupera les fichiers dans le dossier /public lors de l'exécution npm run build comme ceci :

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

Vous avez peut-être remarqué que index.html possède la balise suivante : <_template basic.html /> . Cela place le contenu de index.html dans le fichier de modèle à fentes à /templates/basic.html . Ce format de balise HTML personnalisé fonctionne également dans les fichiers .md .

Modèles

Les modèles peuvent être utilisés avec /pages pour fournir un cadre prêt à l'emploi pour vos pages. Utilisez une balise <_slot /> dans le fichier modèle pour fournir un point d'entrée pour votre contenu. Ouvrez /templates/basic.html et recherchez :

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

Il s'agit d'un emplacement variable, nommé title , dans un fichier modèle, avec une valeur par défaut facultative.

L'utilisation de ce qui suit comme balise de modèle à l'intérieur de /pages vous permettra de saisir une valeur personnalisée dans le modèle, à partir d'une page de contenu :

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

Composants

Le dossier /components est simplement utilisé pour les composants réutilisables. La balise <_import> est utilisée pour importer des composants dans d'autres fichiers HTML, dont un exemple se trouve dans /templates/basic.html .

 < _import header.html />

La balise <_import> peut également être utilisée pour importer le contenu de tout autre type de fichier (JS, SCSS, etc.), après avoir d'abord regroupé la source.

SRC

Placez les fichiers Javascript dans le dossier /src . La balise suivante sera convertie en une balise d'importation <script> normale, liée à votre fichier /src/main.js :

 < _script main.js />

Les importations ES6 sont entièrement prises en charge et le fichier résultant sera transpilé avec Babel, fourni avec Rollup et minifié.

Styles

Le dossier /styles est utilisé pour votre CSS/SCSS. La balise suivante sera convertie en une balise d'importation CSS <link> standard, liée à votre fichier /styles/main.scss compilé :

 < _style main.scss />

Toutes les fonctionnalités node-sass sont entièrement prises en charge, y compris @import .

Actifs

Les actifs statiques sont placés ici, c'est-à-dire les polices, les images, les icônes. Tout ici sera transféré dans le dossier correspondant dans le répertoire racine, par exemple :

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

Remarques

Balises HTML Keystone

• Chaque balise HTML Keystone personnalisée peut être utilisée n'importe où dans un fichier HTML, même dans d'autres attributs HTML, en dehors des autres balises Keystone.
• Pour toutes les balises Keystone personnalisées, vous pouvez également utiliser un attribut src pour cibler un fichier dans n'importe quel dossier : <_template src='myfolder/myfile.html' /> .
• Tous les chemins sont relatifs au dossier contenant package.json , n'utilisez pas de barre oblique initiale sauf si vous souhaitez accéder à un fichier en dehors du projet.
• Les attributs des balises HTML Keystone peuvent utiliser des guillemets « simples », « doubles » ou « backtick ».

Chargement dynamique

• Le chargement dynamique récupère le lien du site Web local et remplace le contenu de la page actuelle par la nouvelle page, sans recharger ni changer de page.
• Lorsque le chargement dynamique est activé, l'état de la page (par exemple, les valeurs saisies, la position de défilement) n'est pas enregistré lors de l'utilisation du bouton Précédent.
• Lorsqu'un lien est cliqué, la classe .keystone-page-loading est définie pour display: block . Si la classe est définie pour display: none dans le CSS, cela peut être utilisé pour créer un indicateur de chargement.
• Désactivez le chargement dynamique dans keystone.config.js.

Générateur d'index de recherche

• Le générateur d'index de recherche génère un fichier, search.json , dans le répertoire racine. Il s'agit d'un tableau JSON contenant un objet pour chaque page, répertoriant le contenu du texte, le titre et le chemin de la page.
• Toutes les balises HTML sont supprimées de la page et seul le texte est conservé et stocké.
• Ce fichier peut être récupéré et interrogé via une fonction de recherche de site Web, pour trouver facilement quelle page contient quel contenu.
• Désactivez l'assistant de la barre de recherche dans keystone.config.js.

Divers

• Le dossier public est ignoré par Git, supprimez la ligne public de .gitignore si vous souhaitez l'utiliser pour le valider dans Git.

Mise à jour de Keystone

• Remplacez le numéro de version dans package.json par la version vers laquelle vous effectuez la mise à jour et exécutez npm install keystone-ssg , pour une mise à niveau rapide.

API

Balises

Étiqueter	Description	Attributs
<_template>	Importe le fichier actuel dans un <_slot> dans le fichier modèle	[nom du fichier], [nom de la variable], src
<_slot>	Utilisé dans un fichier modèle comme point d'entrée pour le fichier importé	Aucun
<_var>	Utilisé dans un fichier modèle pour être remplacé par une variable extraite de <_template>	[nom de la variable], par défaut
<_import>	Importe un composant	[nom du fichier], src
<_script>	Crée une balise <script> liée au script fourni	[nom du fichier], src
<_style>	Crée une balise <link> reliant au fichier CSS fourni	[nom du fichier], src

Commandes NPM

Commande	Description	Différences de sortie
npm run dev	Construit le site Web pour le développement, puis démarre le serveur de développement Keystone.	Des cartes sources en ligne sont générées. Le script du serveur de développement est injecté.
npm run build	Construit le site Web pour la production.	Le bundle est compacté et minifié.

Fichier de configuration

Le fichier de configuration est keystone.config.js

Option	Description	Défaut
Liens dynamiques	Permet des liens locaux chargés dynamiquement sur votre site Web Keystone, aucune actualisation nécessaire	vrai
rechercheFichier	Génère search.json dans le répertoire racine	vrai
cheminindex	Le répertoire racine de votre site Web	'/'
port	Le port du serveur de développement, localhost : 8080	8080
ports	Un deuxième port utilisé pour le serveur de développement	8081
devServerIp	L'emplacement du serveur de développement, localhost :8080. Remplacez par l'adresse IP locale de votre appareil pour afficher le serveur de développement sur les appareils locaux (exemple : « 192.168.1.103 »).	'hôte local'
regardé	Les répertoires surveillés par le serveur de développement Keystone, qui forceront une recompilation et un rafraîchissement de la page lorsque les fichiers seront modifiés	['modèles', 'pages', 'actifs', 'composants', 'src', 'styles']
construire	Le répertoire des pages de contenu	'pages'
servi	Le répertoire contenant le site web généré	'publique'
fullRecompile	Forcer une recompilation complète de tous les fichiers après chaque changement de fichier en mode développement	FAUX

Disposition du répertoire par défaut

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

Erreur de plug-in

Si vous rencontrez un PLUGIN_ERROR après l'installation et l'exécution de l'exemple, il s'agit d'un problème Babel, exécutez la commande suivante pour le résoudre :

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