stl-statilque-litterateur/help

STL: Statique Littérateur

STL est une évolution du projet GSL. STL permet de créer un ou plusieurs sites web/blogs statiques, en fonction de leur nom de domaine.

Tout comme GSL, STL reprend une grande partie de l'écriture nouvelle de vos articles, en apportant quelques évolutions. Les articles sont donc au format .stl.

Fonctionnement de STL ; le dossier de base

Contrairement à GSL, vos articles et les pages de votre site web sont situés dans le même dossier de base. Pour obtenir ce dossier de base, et configurer votre domaine, vous devez d'abord vous placer dans le dossier de votre choix, puis lancer la commande de configuration.

cd MON-DOSSIER-PREFERE
stl domain new

# Vous pouvez également pré-remplir votre domaine en fonction de l'URL
stl domain new https://mon-site.xyz

Dans ce dossier de base (MON-DOSSIER-PREFERE), après la configuration de votre domaine, vous trouverez de nouveaux dossiers :

• articles/
• • images/
• • files/

Les sous-dossiers images/ et files/ sont proposés afin de faciliter la réutilisation d'images et de fichiers (PDF, ou autres) déjà présents dans un autre article. Lors de la synchronisation, il seront copiés à la racine wip de votre serveur. Le but : faire en sorte que le navigateur n'ait pas à recharger un même fichier depuis une URL différente - ce qui plomberait la rapidité d'affichage de la page et l'intérêt d'un site statique. L'utilisation de cette fonction dans vos articles est simple ; voir la documentation expliquant comment écrire un article dans le dossier help.

Dans le dossier du serveur (/var/www est un exemple), vous trouverez les dossiers suivants :

• /var/www/DOMAIN/wip/
• • template (logos, styles.css, sidebar.html, footer.html, metas.html...)
• • images
• • files
• /var/www/DOMAIN/www/ (non créé pour une installation locale)
• • template/
• • images
• • files

Installation (server, ou local)

Il est possible d'utiliser STL de 2 manières différentes. Lors de la configuation d'un nouveau domaine, vous devrez choisir entre une installation faite sur un serveur distant, et une installation faite en local (sur votre PC). Vous pouvez bien sûr choisir une installation de type "server" sur votre PC, si celui-ci sert de serveur web.

Concernant la décoration du site (styles.css, logos), les fichiers devront être placés dans le dossier serveur /wip/template/ (créé par STL lors de l'ajout d'un domaine).

Installation "server"

À choisir si votre PC sert de serveur web, ou si vous avez installé STL sur votre serveur distant.

Lorsque vous installez STL, sur votre serveur distant, vous pouvez gérer pour un même nom de domaine, votre site sur 2 adresses URL différentes. La version WIP, permet de prévisualiser les modifications apportées à vos pages (sans modifier celles sur WWW) avant de les valider sur votre site officiel.

Lorsque votre site prévisualisé sur WIP vous plaît, vous pouvez alors synchroniser le dossier WIP sur WWW grâce à la commande :

# Pour publier un article précis
stl publish (ARTICLE)

# Pour publier tous les articles dans WIP
stl publish all

Note : cette commande crée automatiquement le flux RSS dans WIP avant de tous synchroniser sur WWW.

Installation "local"

À choisir si vous voulez utiliser STL sur votre PC, et synchroniser vous-même le dossier WIP sur votre serveur distant. Inutile donc, d'installer STL sur le serveur distant.

Lors d'une utilisation locale, STL ne crée pas le dossier WWW, et ne synchronise donc pas le dossier WIP vers WWW. C'est à vous de le faire (via ssh, par exemple).

Vous devrez lorsque votre site vous plaît localement lancer la création du flux RSS - avant de synchroniser votre site local sur votre serveur distant - avec la commande :

stl rss

Utilisation de STL

Afin de gérer vos articles, vous devez vous placer dans MON-DOSSIER-PREFERE. L'autocomplétion est activée et personnalisée pour vous aider à trouver (ARTICLE.stl).

Créer votre arborescence

Dans MON-DOSSIER-PREFERE, vous trouverez le dossier "articles". Celui-ci sert de base à votre domain.xyz sur votre serveur. C'est dans ce dossier "articles", que vous pouvez créer vos articles et vos sous-dossiers. Il est à noter que le nom de l'article est important, puisque STL l'utilisera en le transformant en .html. Il est donc recommandé - mais pas obligatoire - de nommer vos articles index.stl, pour obtenir une page index.html. Si vous voulez créer une page 404, nommez votre article 404.stl à la racine du dossier "articles".

Convertir votre article en HTML

Placez vous dans MON-DOSSIER-PREFERE.

Avant de pouvoir convertir votre article, STL dispose d'un système de vérification de la syntaxe STL. Si des erreurs sont trouvées, un système de logs vous aidera à corriger ces erreurs.

# N'oubliez pas d'utiliser l'autocomplétion
stl check (ARTICLE.stl)

Vous pouvez maintenant le convertir en HTMl dans le dossier wip

stl wip (ARTICLE.stl)

Utiliser la sidebar

C'est la seule partie du site qui est semi-statique. STL fait appel à nginx, qui va se charger de traduire la balise HTML <!--# include file="..." -->, et afficher le rendu du fichier sidebar.html

Chaque article, une fois convertit avec l'argument wip peut être placé dans la sidebar à la position désirée, entre 1 et la valeur maximum décidée, lors de la configuration du domaine.

stl sidebar add 1 (ARTICLE.stl)

Vous pouvez également décider de placer un article ausitôt convertit avec l'argument wip sidebar=POSITON

stl wip sidebar=2 (ARTICLE.stl)

Documentation de STL

Les fichiers de documentations sont dans le dossier help. Le README est accessible depuis la ligne de commande, comme les arguments utilisables.

stl help
stl readme

Dépendances

STL est écrit en bash, et a besoin des utilitaires

• gawk
• rsync
• nano
• curl