stl-statilque-litterateur/help/README.md

# 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 :

```
stl sync
```

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