stl-statilque-litterateur/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 (serveur, ou localeà
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 sur un serveur distant, et une installation uniquement en
local (sur votre PC). Vous pouvez bien sûr choisir une installation
serveur sur votre PC, mais il n'y a pas d'intérêt.

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 sur un 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 www) avant de les valider sur WWW.

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.

### Installation sur un PC local
Lors d'une utilisation locale, la prévisualisation WIP sur un serveur
distant ne sert à rien. En effet, lorsque vous créez des pages, celles-ci
étant déjà placées dans votre dossier de serveur local wip. Vous pouvez
ouvrir les pages HTML dedans avec votre navigateur. Si vous êtes satisfait
de vos pages sur votre serveur local, vous pouvez directement transférer
votre dossier "wip" (ex: /var/www/domain.xyz/wip) local vers votre serveur
distant (en général /var/www/), par exemple, via SSH. De ce fait, vous
n'avez même pas besoin, d'instaler STL sur votre serveur
distant. Pour générer votre flux RSS, utilisez 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 erreeurs 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 en HTML "include", 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 dans la sidebar

```
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

Oui, pour l'instant, c'est tout ;)