20/11/2019

Rédaction des articles mantra

Conventions utilisées pour la construction des articles du site

Quelques règles mais pas trop !

Ecriture d'un automate logiciel nommé mantra permettant la création automatique d'un site complet.

Le choix s'est porté sur la génération d'un site statique pour des raisons de simplicité (pas de backend), de rapidité et de sécurité.

Contrairement à des générateurs statiques comme hugo ou jekyll orientés posts (style blog), celui-ci est orienté CMS (Content Management System) ou base de connaissance...

En effet chaque article est autocontenu dans un répertoire/directory avec tous ses fichiers annexes associés (images, sons, films, documents annexes).

Le but étant la simplicité de gestion du site et la possibilité qu'il y ai plusieurs rédacteurs séparés et autonomes...

Axiomes :

  • Le créateur/rédacteur se focalise sur le contenu uniquement.
  • La mécanique de gestion du site doit être transparente pour le rédacteur.
  • Récupération et modifications faciles des articles.
  • Site léger, full responsive et donc adapté aux mobiles/tablettes.

Contenu rédactionnel

Utilisation d'un éditeur de texte orienté Markdown, la plupart des sites Web utilisent cette technique rédactionnelle. Le gros avantages du codage markdown est qu'il peut être écrit avec n'importe quel éditeur de texte présent dans le système utilisé.

Les balises de mise en évidence du texte sont simples à comprendre pour un humain à l'inverse du codage par balises HTML !

Voir https://fr.wikipedia.org/wiki/Markdown

Un article externe reprenant les avantages du format markdown :

https://www.quaternum.net/2018/10/18/markdown-comme-condition-d-une-norme-de-l-ecriture-numerique

Définition d'un article

Un article est un conteneur (dossier ou répertoire) contenant un fichier article.md ainsi que tous les fichiers en lien avec celui-ci (pdf, word, mp3, mp4, jpg, _jpg). La règle de nommage est la suivante:

AAAA-MM-JJ@Domaine--Titre_de_l_article

D'abord la date au format W3C année-mois-jour, ce format permet naturellement d'être classable (plus récents) sur la page d'accueil. Le site fait apparaître les 4 articles les plus récents. Pas d'accents dans le nom de l'article ni dans le domaine !

@Domaine

C'est du ressort du rédacteur de créer une catégorie à laquelle appartient l'article.

Le système montre les différents domaines abordés dans le site. Pas d'accent pour le domaine !

--nom_de_l_article comme indiqué, pas d'espaces et pas d'accents.

Le nom des images intégrées à l'article doivent être de la forme "_image.jpg ou png". Il est important de limiter la taille des images à 600 pixels voire 720.

Utiliser la forme Markdown d'insertion d'une image :

![](_image.jpg ou png)

En ce qui concerne le fichier principal article.md, il est important que les premières lignes soient en texte seul, si vous voulez insérer une image, faite le après ces quelques lignes...

Par convention, la première ligne est le titre de l' article (et sera repris dans la page HTML sur fond jaune).

Le système gère l'insertion de fichiers mp3 (podcast audio), mp4 (vidéo). Tout le code de création d'un lecteur vidéo ou audio est inséré automatiquement dans la page HTML.

En ce qui concerne les images au format jpg à afficher, elles le sont après l'article proprement dit, le code HTML est fluide et donc elles sont redimensionnées automatiquement par le framework CSS.

Le nom des fichiers images ne doit pas commencer par un _ (underscore) car c'est réservé pour les images présentes dans le corps même de l'article.

Si un fichier Markdown du même nom que l'image mais avec l'extension md est présent, il est transformé en code HTML et placé en dessous de celle-ci. Cela permet de créer des fichiers légendes éventuellement pour chaque image. Ceci n'est pas obligatoire !

La règle est: nom_image.jpg --> nom_image.jpg.md

Il est possible de placer autant de fichiers souhaités, en relation avec l'article, dans le dossier, le système créera les liens HTML vers ceux-ci automatiquement.

In fine s'il y a d'autres fichiers en code markdown, on les affiche en dessous cela permet d'ajouter d'autres rédactionnels éventuels sans retoucher le fichier article d'origine !

Ajout du 31 juillet 2019 :

Possibilité de rajouter un commentaire sonore pour une image, la règle de nommage est nom_image.jpg.mp3, le système crée le code pour le lecteur audio juste en dessous de la photo !

Ajout récent

L'automate se sert de la première image "_image.jpg" présente dans l'article pour créer la miniature sur la page d'accueil du site et sur chaque page de domaine.

S'il y a pas d'image contenu dans l'article proprement dit, il prend la première image dont le nom commence par A (cela permet de choisir celle qui sera mise en valeur), sinon l'automate insère un logo par défaut (fichier "_logo.jpg").

Si un répertoire nommé sticky existe, il est traité comme un article et inséré en bas de la page d'accueil et de chaque page de domaine.

Etonnant non ?

Retour