gsl-statique-litterateur/README.md

# GSL: Statique Littérateur
------------------------------------------------------------------------

GSL est un générateur de blogs/sites-web basé sur leur nom de domaine,
écrit en bash, afin de ne réduire ses dépendances au minimum. Les pages
générées sont presque entièrement statiques, à l'exception du module de
liste des derniers articles. Nginx peut être facilement configuré pour
interprêter ce module.

# Dépendances
------------------------------------------------------------------------

- bash
- coreutils
- curl (to check Posts links response)
- rsync


# GSL: Installation
------------------------------------------------------------------------
Une procédure d'installation via un setup est en cours de test. Il est
aussi possible et recommandé sous debian de l'installer grâce à son 
paquet deb.

Pour une installation manuelle, clonez ce dépôt, et copiez les dossiers
déjà pré-établis dans le système. GSL n'utilise pas sudo, il vous faut
donc donner les droits aux dossiers (chown -R) à l'utilisateur
(sauf au dossier /usr/local/bin). Pour ce dossier, vous donnerez les droits
via chown USER:USER /usr/local/bin/gsl

## Configuration du DOMAIN (selon le choix de l'utilistaeur via $ gsl new) :
- HOME:   ~/.config/gsl
- GLOBAL: /var/lib/gsl
- Dossier: --Prefix/domains/ (créé par GSL via $ gsl new)

### Données du DOMAIN :
- Dossier: --Prefix/DOMAIN/ (créé par GSL)
- - Fichiers: DOMAIN.conf, authors.db (créé par GSL)
- - Dossier: --Prefix/DOMAIN/templates/ (créé par GSL - pour vos css, logos...)

## Dossier de configuration de GSL : /etc/gsl/
- Fichier: gsl.conf

## Dossier principal : /var/lib/gsl/
- Folder: db (créé par GSL)
- Dossier: helps
- Dossier: scripts
- Fichier: README.md, README-english.md

## Dossier des logs: /var/log/gsl/
- Fichier: gsl.log (créé et géré par GSL via $ gsl log [OPT]...)

## Dossier de l'éxécutable : /usr/local/bin/
- Fichier: gsl

## Dossier d'autocomplétion : /usr/share/bash-completion/completions/gsl/
- Fichier: gsl

# Comment configurer un domaine
------------------------------------------------------------------------

Des questions vous seront posées lorsque vous voudrez ajouter un domaine
(exemple.com). Les données renseignées seront utilisées pour créer le
fichier DOMAIN.conf. Une question spécifique pour les fichier des articles
vous sera posée afin d'établir un dossier de stockage de vos articles.
Vous pourrez en créer à loisir autant que vous voulez plus tard.

```
# helps
gsl help
gsl help new
gsl help install

# Ajouter un domaine
gsl new
```

## Définir un dossier pour les articles du DOMAIN 
Si ce n'est pas déjà fait par GSL, ou que vous voulez ajouter un dossier
pour y stocker et convertir en HTML vos articles pour un DOMAIN précis :

- Ajouter/créer un dossier de votre choix
- Créer dedans, un fichier vide nommé gsl.DOMAIAN (gsl.exemple.com)

## Ajouter un auteur
```
cd MON-DOSSER-ARTICLES
gsl author add
```

## Créer un article
Le moteur de convertion est nouveau, et est un mélange entre markdown et
reSTructuredText. Il est simple à apprendre et à utiliser.

- Créer un fichier (monarticle).gsl (extension .gsl)
- Suivez le guide plus bas pour comprendre les notions

Vous devrez le faire valider par GSL :
```
gsl check
```

## Convertir un ou tous les articles
Si votre article n'a pas d'erreurs, vous pouvez le convertir en HTML.

```
gsl make
```

Votre article sera prêt dans le dossier webserver (ex: /var/www/DOMAIN/wip)
Vous pourrez donc vérifier son rendu.

Si vous êtes satisfait, vous pouvez le déployer "officiellement" dans www

```
# Vous pouvez utiliser l'autocompletion pour les articles
gsl www add (monarticle.gsl)
```

# Créer un Template
------------------------------------------------------------------------

Vous devrez pour que votre site soit à vôtre goût créer et définir les
styles dans styles.css. Placez ce fichier (en fonction du choix de votre
configuration du DOMAIN) dans :
- HOME:   ~/.config/gsl/domains/DOMAIN/templates/
- GLOBAL: /var/lib/gsl/domains/DOMAIN/templates/

Astuce: Une fois votre article créé, vous verrez dans sa source que
beaucoup d'éléments ont une class="acronymechoisi_***". Utilisez ces classes.
Pour mettre à jour et voir vos modifications

```
gsl sync
# ou (si vous modifier le header/footer)
gsl make -F
```

# Comment écrire un article
------------------------------------------------------------------------

Votre article doit contenir 2 sections. Les Metas avant #1 et 
l'article à partir de ce repère (servant de titre h1).

- METAS : configurer votre article (titre, date, liens...)
- ARTICLE :  Contenue rédactionnel avec quelques marqueurs (gras...)

## METAS obligatoires (avant #1)


```
title: POST TITLE
slug: POST-TITLE (si espaces, GSL les convertira en -)
info: DESCRIPTION (À propos de cet article)
author: NAME (doit être enregistré via ($ gsl author add)
date: YYYY-MM-DD
tags: TAG1,Mon TAG2,TAG3 (séparé par une virgule)
```

### Page ou Article ?
Vous pouvez spécifiez pour chaque article si c'est une page ou un article
Si non renseigné, GSL ajoutera le type: post (article) par défaut à la 
première ligne de votre article

TYPE:
- post < Article
- page < Page (créer vos pages: index, 404, about...)

```
type: TYPE
```

GSL créera vos fichier HTML selon le "slug" renseigné. Ne pas ajouter .html
Selon le type: 

- post < /POST-TITLE/index.html
- page < /POST-TITLE.html

## METAS optionnelles (avant #1)
Définir les marqueurs (abbr:, link:...) et utilisr " : " comme séparateur

```
abbr: COURT : LONG
file: NOM : NOM-DU-FICHIER : Text alternatif
link: NOM : URL : Text alternatif
code: NUMERO : NOM-DU-FICHIER : Text alternatif
image: NUMERO : NOM-DU-FICHIER : TEXT-ALTERNATIF
```

## Contenu de l'article:
Les marqueurs (ex __Mon-super-fichier) doivent commencer et finir sur
la même ligne. Pour les abréviations (abbr:), écrivez juste (ex: COURT).


```
# Paragraphes
Au début d'une nouvelle ligne, ouvrez avec ( et fermez avec ).
Vous pouvez utiliser 4 classes de paragraphes différentes : ( 1 ( 2 ( 3
( 2
Paragraphe avec une classe 2 (css)
)

# Liens
(définir en METAS. ex: link: Mon lien : URL : Alt text)
_Mon lien
_Mon lien+ # Pour ouvrir dans un nouvel onglet

# Fichiers
(définir en METAS. ex: file: Mon fichier : FILENAME : ALT-TEXT
__Mon fichier

# Images
(définir en METAS. ex:  image: 1 : FILENAME : ALT-TEXT
_image:1
_image:1:r

:[l|r|c] (gauche, droite, centre)

# Block-Code depuis un fichier:
(définir en METAS code: 1 : FILENAME : Alt Text
_code:1

# Écrire en très gras
**c'est du surgras**
c'est in**défini**ssable
il ad**juge** : pas de pub !

# Gras
*c'est en gras*
...

# Italique
écrire /en italique/

# Code en ligne (¤ = alt-gr + $ sur clavier FR azerty)
¤gsl help -w¤

# Citation simple
(au début de la ligne, mettez 3x -)
---
(
Une citation simple dans un paragraphe
)
---

# Citation avancée
---
_cite : Richard Matthew Stallman
_link : https://stallman.org/
_lang : en
(
In the free/libre software movement, we develop software that respects
users' freedom, so we and you can escape from software that doesn't. I
could have made money this way, and perhaps amused myself writing code.
But I knew that at the end of my career, I would look back on years of
building walls to divide people, and feel I had spent my life making the
world a worse place
)
---

# Citation avancée : optionnel
_year: 2021
_book: Esperanza 64

# Créer des listes
(utilisez = pour définir l'arborescence). L'arborescence est "infie")
(chaque contenu de la liste doit être sur la même ligne)

(
Voici une liste
= Fruits : *mangez-en*
== Kiwis
== Fraises
=== pas mûres
== Bananes
= Légumes
== Épinards
Fin de la liste
)
```

# HELP COMMAND
```
$ gsl [ARG]
  readme                  : Show README.md instructions
  help | -h [OPT]         : This Help
    install               : Show process installation
    new                   : Adding a DOMAIN
    write | -w            : How to write a Post

  new | -N                : Add and configure a new DOMAIN
   
  log | -L [OPTS]         : Show logs from all sessions
    clean | -C            : Logs saved to {DATE}.gsl.log and cleaned
    -i | -w | -e          : from levels (infos, warnings, errors)
    -s                    : from last session only
    [TERM]                : [TERM] : case insensitive, regex 'T1.*T2'
                            (i.e. $ gsl log -e -s code)

  author | -A [OPT]       : List authors from DOMAIN set in PWD folder
    add                   : Add author(s) for DOMAIN
    remove                : Remove author(s) for DOMAIN
   
  edit | -E [FILE]        : Open in default EDITOR [FILE] or with nano
  db [FILE]               : Show DB statuses from [FILE]

  sync [OPT]              : Sync Templates to www and wip
    wip                   : Only to wip server (also done with make)
    www                   : Only to www server (also done with www)
    

  check | -C [OPT] [FILE] : Check Posts errors from PWD folder or [FILE]
    -F                    : Force check again
    
  make | -M [OPT] [FILE]  : Convert Posts from PWD folder or [FILE]
                            to HTML file in server
    -F                    : Force Make again
    
  post-list [OPT] [FILE]  : Add post again from [FILE] to Last-Posts List
                            (When converting new post, it will be added)
    Pin                   : Set Post from [FILE] to first in Last-Posts List
    Add                   : Add Post from [FILE] to last in Last-Posts List
  
  www [OPT1] [OPT2]       : Add/Remove Post from www server
    [OPT1]:
      add                 : Add all/[FILE] to www server
      rmove               : remove all/[FILE] from www server
    [OPT2]:
      all                 : Select all post with wip statuses
      [FILE]              : Select specific post (if wip status)
  
  version | -v            : Show local versionn
  -vv                     : Shown local and repo Versions
```