Table des matières

Comment utiliser Catium

Ce document existe pour apprendre à utiliser Catium sans pour autant lire toute la documentation se trouvant aujourd’hui dans cet article.

A noter, Catium est conçu pour être modifiable et même inciter à l’être. Ainsi ce document documente comment utiliser Catium dans sa version “minimale”. Des cas de modifications relativement simples seront couverts à la fin de ce document.

Il ne faut pas s’attendre à pouvoir modifier Catium facilement sans aucune compétence en make/markdown/shell/html. L’idée est de faire de Catium un logiciel favorisant l’apprentissage des ces technologies dont on estime qu’elles constituent un socle de compétences de bases en informatique. On pourrait évidemment débattre de ce que l’on inclu dans ce socle ou pas.

Dépendances

En l’état Catium nécessite

Pour la suite de ce document nous partons du principe que le site est écrit en markdown.

Générer le site

Catium utilise GNU Make pour orchestrer la génération du site. Les règles de génération sont écrites dans le fichier makefile. Pour lancer la génération faire

make

Il est possible d’accélérer le processus en parallélisant avec l’option -j. Pour purger les fichiers produits faire

make clean

Il n’est pas toujours nécessaire de faire un clean avant de faire un make, les fichiers seront réécrits. La génération du site va transposer les fichiers et l’arborescence source - dans ./contents - vers la destination - le dossier ./public. Ainsi avec l’arborescence

./contents
├── archives
│   └── index.sh
├── articles
│   └── youtube
│       ├── arguments-to-plumber.patch
│       ├── display_author.patch
│       └── index.sh
├── index.sh
└── notes
    └── laconvivialite
        └── index.sh

make génère l’arborescence

./public
├── archives
│   ├── index.html
├── articles
│   └── youtube
│       ├── arguments-to-plumber.patch
│       ├── display_author.patch
│       ├── index.html
├── index.html
└── notes
    └── laconvivialite
        └─── index.html

Pour chaque fichier présent dans ./contents le makefile a une règle expliquant à make ce qu’il faut faire. Sans rentrer dans les détails, les fichiers .sh sont transformés en .html et copiés dans une arbo identique recrée sous ./public.

Créer le contenu

L’exemple précédant se base sur le contenu du site Katzele mais vous voulez évidemment faire le votre. Imaginons partir de zéro.

Template HTML

Il nous faut au moins un template HTML qui structurera nos pages. Ce sera l’échaffaudage pour nos pages. Ce template devra se trouver dans le dossier ./layouts/html.

Prenons celui-ci comme exemple :

layout() {
<<@@ cat
<!DOCTYPE html>
<html>
<head>
    <title>${title?La page dont le chemin s'affiche au dessus nécessite un titre}</title>
    ${STYLE:+<link rel="stylesheet" href=\"$STYLE\" />}
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1.0">
    <meta name="description" content="$description" />
    <meta name="author" content="$author" />
</head>
<body>
    <main>
        $(show main)
    </main>
</body>
</html>
@@
}

Les lignes layout() <<@@ cat et à la fin @@ déclarent une fonction shell qui contient un heredoc. Si vous voulez en savoir plus lisez cet article ou lisez le manuel de dash. Vous pouvez faire abstraction sinon.

Le contenu qui se trouve entre ces deux lignes est un mélange d’HTML pur, de variables shell et d’expansion de variables shell. Je ne vais pas les expliciter ici. Ce template convient pour générer des pages très simples, sans header ni footer, simplement le corps de la page que l’on écrit en markdown. Si cela vous convient vous pouvez ne pas y toucher. Par défaut la feuille de style qui sera utilisée est ./contents/style.css. Elle contient le thème de Katzele, vous pouvez la modifier à votre guise.

Pour d’éventuelles modifications du template ce qu’il faut à minima retenir est que vous pouvez ici ajouter de l’HTML comme bon vous semble et avoir recours à la commande show nom_de_section pour ajouter des sections que vous renseignerez en markdown dans vos fichiers sources. Si vous voulez des exemples de modification voir plus loin dans ce document. Pour des exemples de sites aboutis voir la galerie.

Fichier source markdown

Les fichiers sources des pages doivent comporter l’extension .sh et être exécutables. Ils doivent commencer par la ligne

#! /usr/bin/env ./page

pour être préprocessés par le script page. Ils doivent ensuite contenir un ensemble de métadonnée. En l’état Catium propose

On renseigne ces métadonnées en appelant, dans le fichier sh, les différentes “variables”. Par exemple pour une page d’accueil

title: "Page d'accueil de mon site"
author: moi
publication: 2023-06-21
description: "Site de machin chose, bidule à chouette à truc muche"

Il faut ensuite écrire le contenu markdown. Pour cela faire appel à l’instruction section: marquant le début du markdown. Il faut mettre à la suite de cette instruction la section du template dans laquelle on veut que le contenu qui suive aille. Dans notre exemple de template il n’y a qu’une section (marquée par la commande $(show main)) qui remplira bêtement la balise main, unique balise du body. C’est le mot clef suivant show et non pas le nom de la balise HTML qu’il faut retenir et faire correspondre avec ce que l’on va écrire dans le fichier markdown. Il est naturel que la balise et le nom de la section soient identiques mais cela n’est pas nécessaire. Pour y mettre du contenu nous pouvons donc écrire :

section: main
# Le site de machin chose
Salut !

## Ma vie mon oeuvre

J'ai travaillé ici, là-bas et accompli cela

  * premier truc
  * second truc
endsection

Il faut fermer l’instruction section: avec un endsection. Au final notre document ressemble à :

#! /usr/bin/env ./page
title: "Page d'accueil de mon site"
author: moi
publication: 2023-06-21
description: "Site de machin chose, bidule à chouette à truc muche"
section: main
# Le site de machin chose
Salut !

## Ma vie mon œuvre

J'ai travaillé ici, là-bas et accompli cela

  * premier truc
  * second truc
endsection

Si ce fichier se nomme index.sh et se trouve à la racine du dossier ./contents alors exécuter make génèrera ce index.html dans ./public :

<!DOCTYPE html>
<html>
<head>
    <title>Page d'accueil de mon site</title>
    <link rel="stylesheet" href="style.css" />
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1.0">
    <meta name="description" content="Site de machin chose, bidule à chouette à truc muche" />
    <meta name="author" content="moi" />
</head>
<body>
    <main>
        <h1>Le site de machin chose</h1>
        <p>Salut !</p>
        <h2>Ma vie mon oeuvre</h2>
        <p>J'ai travaillé ici, là-bas et accompli cela</p>
        <ul>
            <li>premier truc</li>
            <li>second truc</li>
        </ul>
    </main>
</body>
</html>

Dernière astuce, en dehors des blocs section: nom_de_section ... endsection vous pouvez exécuter du shell. Ainsi il est possible, avec votre langage préféré, de générer du markdown. Cela peut être pratique quand l’on veut générer quelque chose en fonction d’un contenu qui change souvent et dont on ne connaît pas, à priori, la teneur. Par exemple un plan de site. Pour ce faire écrivez le code que vous souhaitez et pipez le dans la commande save suivi du nom de la section dans laquelle vous voulez que le contenu apparaisse. Ainsi, en reprenant la fin du document :

J'ai travaillé ici, là-bas et accompli cela

  * premier truc
  * second truc
endsection

echo "[Un autre site cool](lien_vers_site_cool)" | save main

Ajoutera un lien dans la section main

    <li>premier truc</li>
    <li>second truc</li>
    </ul>
    <p><a href="lien_vers_site_cool">Un autre site cool</a></p>
    </main>
</body>
</html>

Cela peut être pratique pour générer du contenu dynamiquement en fonction d’autres morceaux du site, de la date etc.

Voilà, à partir de là si vous savez écrire du markdown et que vous n’avez pas besoin d’autre chose que des pages simplistes comme celles générées avec le template fourni vous avez les cartes en main pour créer votre site avec Catium. Cela dit l’esprit de l’outil est qu’il est de nature “hackable” avec des compétences que l’on juge, dans le collectif, comme étant de bonnes candidates pour être des compétences “socles” dans l’informatique.

En dessous nous voyons quelques cas élémentaires de modifications qui pourraient vous intéresser ou vous mettre sur la bonne piste. Pour des exemples plus aboutis voir la galerie.

Modifier catium

Admettons que vous vouliez apporter les modifications suivantes à l’existant :

Ajouter une métadonnée

Vous l’avez peut-être remarqué, il existe une balise <html lang="fr"> dans notre template. Cette balise sert à déclarer la langue du contenu qui suit. Cela permet entre autre aux lecteurs d’écrans de lire correctement le contenu de la page. Si vous tenez un site bilingue vous pourriez vouloir spécifier la langue article par article et non pas de façon figée dans le template.

Pour cela ajoutons une métadonnée qui nous utiliserons au début des articles. Pour ajouter une métadonnée il nous faut modifier le fichier page qui contient le code pour les rendre opérantes. Dans ce fichier, ajouter une métadonnée revient à déclarer un nouvel alias et une fonction correspondante. En ce basant sur ce qui existe pour title: :

alias lang:="lang"
lang() lang="$*"

Dorénavant quand on écrira lang: fr" dans un fichier, la variablelang` prendra pour valeur “fr”. Il suffit ensuite de l’appeler au bon endroit dans le template

layout() <<@@ cat
    <!DOCTYPE html>
    <html lang="$lang">
    <head>

Hop, nous pouvons dorénavant déclarer la langue d’un article. Nous pourrions mettre un petit filet pour nous assurer de ne pas oublier d’un déclarer un :

<html lang="${lang?Langue de l'article non déclarée}">

Si la variable est vide (parce que nous aurions oublié de renseigner lang: dans un article) alors la génération du site va se terminer et le message d’erreur sera affiché. Alternativement il est possible de choisir une valeur par défaut comme ceci :

<html lang="${lang:-fr}">

Ajouter une section au template

Admettons que nous souhaitons ajouter un footer et un aside dont nous voulons maitriser le contenu. Rien de plus simple, il suffit de créer les balises qui vont bien et d’appeler la commande show avec les noms des sections.

layout() <<@@ cat
<!DOCTYPE html>
<html lang="fr">
<head>
    <meta charset="utf-8">
    <title>${title?La page dont le chemin s'affiche au dessus nécessite un titre}</title>
    <meta name="viewport" content="width=device-width,initial-scale=1.0">
    ${STYLE:+<link rel=\"stylesheet\" href=\"$STYLE\"/>}
    <meta name="description" content="$description">
</head>
<body>
    <main id="main" class="main">
        $(show main)
    </main>
    <aside id="aside" class="aside">
        $(show aside)
    </aside>
    <footer id="footer" class="footer">
        $(show footer)
        <p>$author</p>
    </footer>
</body>
</html>
@@

Au passage nous mettons le nom de l’auteurice, se trouvant dans la variable $author grâce à l’instruction author:, dans le footer. Dans les sources d’une page il faudrait ensuite appeler section: avec les noms de sections :

section: main
# Titre de l'article
blablalba
endsection

section: aside
truc que l'on raconte dans l'aside
endsection

section: footer
contenu du footer
endsection

A noter, si vous en avez une utilité quelconque, il est possible d’ouvrir et de fermer les section: à votre guise. Le contenu d’une section sera généré dans l’ordre d’apparition dans le document mais les sections n’interfèrent pas entre elles.

Il est donc possible d’écrire :

section: main
# Titre
azdazda
endsection

section: footer
machin
endsection

section: main
bidule
endsection

section: footer
truc
endsection

cela reviendrait à écrire

section: main
# Titre
azdazda
machin
endsection

ection: footer
bidule
truc
endsection

Pareil avec les appels à la commande save nom_de_section suite à un pipe.