rnb-pub : publication en javascript

rnb-pub est un outil simple pour publier rapidement sur le web une série de documents au format markdown sans aucun prérequis côté serveur.

Téléchargement à venir...

Présentation

rnb-pub a été créé dans le but de permettre de publier sur un site web des documents au format markdown sans avoir aucun code à écrire, aucun paramètre à configurer :

  • On déploie le projet tel quel.
  • On déploie son contenu rédactionel.

On se focalise donc essentiellement sur la rédaction du contenu, sans qu'il y ait besoin d'un quelconque paramétrage du serveur web. On peut même utiliser rnb-pub en dehors d'un serveur web, sur une machine locale.

Organisation de l'archive

  • app
  • index.html : la page html de base.
  • index.md : la page d'accueil.
  • L'application se trouve dans le répertoire app.
  • Le contenu sera affiché à l'aide de la page web index.html.
  • Le contenu par défaut est porté par le fichier markdown index.md.

Installation de l'archive

Installation sur un serveur web

Il suffit de dézipper l'archive sur un serveur web et le projet est fonctionnel : afficher la page index.html dans le navigateur web permettra de voir le contenu de index.md.

Installation en local

Vous pouvez utiliser rnb-pub en dehors d'un serveur web en dézippant l'archive n'importe où dans votre système de fichier mais il faudra dés lors afficher la page index.html dans un navigateur web spécialement configuré.

Attention : utiliser rnb-pub avec ce type de configuration de navigateur web peut entrainer des failles de sécurité. Une version malveillante de rnb-pub aurait potentiellement la possibilité d'accéder à des données sensibles de votre machine. Utiliser uniquement un projet rnb-pub téléchargé depuis le site omacronides.com et où le code source javascript est humainement lisible.

Il n'y a plus qu'à rédiger le contenu comme la page index.md.

Rédaction de contenu

Le contenu à afficher doit être rédiger en markdown et le fichier doit obéir à une structure simple inspirée de celle des messages internet (IMF) :

Title: Document title
Date: 2021-10-09

This is the body of the document.
Exemple de document simple.

Un document commence par une ou plusieurs lignes de couple « nom » / « valeur » nommés « en-têtes » (headers), le nom et la valeur étant séparé par un deux-points (« : »). Les en-têtes portent généralement des données décrivant le document comme le titre, la date de rédaction, etc. Ces données seront ensuite affichables dans la page web.

Les en-têtes sont suivies par une ligne vide.

Vient ensuite le corps du document ou « body ». Il consituera le contenu principal de la page web.

Voilà. Rien de plus compliqué. Vous pouvez éventuellement commencer et finir la série d'en-têtes avec une ligne triple-tirets comme cela se fait dans certains moteurs de site web statique :

---
Title: Value 1
Date: Value 2
---

This is the body of the document.
Exemple de document avec des triple-tirets pour encadrer les en-têtes.

Afficher le contenu dans la page html

L'affichage du contenu se fait grâce à la page html « index.html » :

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>rnb-pub</title>
</head>
<body>
    <header>
        <h1 data-prop="title"></h1>
        <p>Date : <time data-prop="date"></time></p>
    </header>
    <main data-prop="body"></main>
    <script src="app/rnb/pub/main.js" type="module"></script>
</body>
</html>

Elle charge le programme javascript à l'aide de l'élément HTML <script>.

Par défaut, la page affiche le contenu du fichier index.md qui fait office de page d'acceuil. Nous verrons plus bas comment afficher d'autres pages.

Les attributs « data-prop »

Les données du document sont affichées dans les éléments HTML portant un attribut « data-prop » correspondant au nom de la donnée. Si nous avons définit un en-tête « title » par exemple, sa valeur sera affichée dans l'élément HTML portant l'attribut data-prop à « title ».

Le corps du document ou « body » sera lui affiché dans l'élément HTML portant l'attribut data-prop à « body ».

Là aussi, rien de compliqué. La seule ligne obligatoire est l'élément <script> qui charge le javascript : il est conseillé de le laisser en tant que dernier enfant de l'élément HTML <body>.

La plupart des données seront affichés dans la page HTML telles qu'elles sont écrites dans le document source, à l'exception du corps du document (body) qui sera transformé en HTML et de quelques autres données au formatage spécifique.

Affichage des dates

Si une donnée est une date au format ISO 8601 simplifié :

Date: 2021-05-30

Si par ailleurs cette donnée est affichée dans un élément HTML <time> :

<time data-prop="date"></time>

Alors rnb-pub sera capable d'afficher une version humainement lisible de cette date dans l'élément :

<time datetime="2021-05-30">30 mai 2021</time>

On verra plus tard qu'il est possible de configurer le format affiché de la date.

Affichage des liens

La déclaration et l'affichage des liens sont importants puisque ce sont eux qui permettent d'ouvrir d'autres pages HTML.

A écrire...

<a rel="prev" data-prop="prev"></a>
prev:
    url: /previous
    text: Go to previous
<a rel="prev" data-prop="prev" href="/previous">Go to previous</a>

On peut aussi ne préciser que l'url si le texte du lien est déjà présent dans la page HTML :

<a rel="prev" data-prop="prev">Go to previous</a>
prev: /previous
<a rel="prev" data-prop="prev" href="/previous">Go to previous</a>

Si l'url du lien commence par « / », rnb-pub considérera qu'il s'agit d'un contenu à afficher et essayera de lire le fichier markdown correspondant. Ainsi, si l'url est par exemple « /pages/page-01.md » ou « /pages/page-01 », rnb-pub essayera de lire le contenu du fichier « page-01.md » dans un répertoire « pages ».

Affichage conditionnel

Il se peut qu'un affichage de données dépendent de l'existence d'une autre donnée où qu'un morceau de code HTML ne soit affichable que si la donnée existe. Cette problématique est gérée par un attribut data-if :

<p data-if="foo">
    this is the « foo » value : <span data-prop="foo"></span>
</p>

Le paragraphe portant l'attribut « data-if » et son contenu ne seront affiché que si la donnée « foo » existe. On verra plus tard que l'on peut définir des tests conditionnels plus complexes.

D'autres contenus que index.md

Le projet n'aurait qu'un intérêt limité s'il ne permettait d'afficher le seul document index.md. Comme la syntaxe des liens décrites ci-dessus permettent de lier d'autres documents, voyons comment organiser une navigation simple entre la page d'acceuil (index.md) et deux autres pages placés dans un répertoire « pages » (vous pouvez évidemment appeler ce répertoire ainsi que les pages qui s'y trouvent comme bon vous semble) :

  • pages
    • page-01.md
    • page-02.md
  • index.html
  • index.md
<!DOCTYPE html>
<html>
<head>
    <title>My website</title>
    <meta charset="utf-8">
    <style>
        html, body {
            background-color: #fff1e5;
        }
    </style>
</head>
<body>
    <header>
        <p><a href="/index" title="Return to home page">Home</a></p>
    </header>
    <main>
        <h1 data-prop="title"></h1>
        <div data-prop="body"></div>
        <nav>
            <a rel="prev" data-prop="prev" title="Previous page">Previous</a>
            <a rel="next" data-prop="next" title="Next page">Next</a>
        </nav>
    </main>
    <script src="app/rnb/pub/main.js" type="module"></script>
</body>
</html>
index.html
Title: My Website

**Welcome to my website** !

Pages available :

• [Page 01](/pages/page-01)
• [Page 02](/pages/page-02)

index.md
Title: Page 01
Next: /pages/page-02

This is the content of page 01.


pages/page-01.md
Title: Page 02
Prev: /pages/page-01

This is the content of page 02

pages/page-02.md

Démonstration

A écrire...

Title: Navigation

• [Page 01](/pages/page-01)
• [Page 02](/pages/page-02)

navigation.md
<!DOCTYPE html>
<html>
<head>
    <title>My website</title>
    <meta charset="utf-8">
    <style>
        html, body {
            background-color: #fff1e5;
        }
    </style>
</head>
<body>
    <header>
        <p><a href="/index" title="Return to home page">Home</a></p>
        <nav id="navigation"></nav>
    </header>
    <main>
        <h1 data-prop="title"></h1>
        <div data-prop="body"></div>
        <nav>
            <a rel="prev" data-prop="prev" title="Previous page">Previous</a>
            <a rel="next" data-prop="next" title="Next page">Next</a>
        </nav>
    </main>
    <script src="app/rnb/pub/main.js" type="module"></script>
</body>
</html>
index.html

Démonstration avec navigation

Aller plus loin

  • app
    • user
      • styles.css
      • script.js
  • index.html
  • index.md
<!DOCTYPE html>
<html>
<head>
    <title>web site title</title>
    <meta charset="utf-8">
    <!-- user stylesheet -->
    <link rel="stylesheet" href="app/user/styles.css">
</head>
<body>
    <header>
        <h1 data-prop="title"></h1>
    </header>
    <main data-prop="body"></main>
    <!-- user script -->
    <script src="app/user/script.js" type="module"></script>
</body>
</html>

Styles des pages

rnb-pub ne s'occupe pas de la maquette, du design de la page web. Ce n'est pas son rôle. Comme le contenu est affiché dans la page index.html, vous pouvez personnaliser son apparence comme n'importe quelle autre page web avec une feuille de styles en cascade.

Néanmoins, si vous voulez appliquer quelques styles de base, rnb-pub fournit un fichier css minimal qu'il suffit d'importer dans la page index.html

@import '../rnb/pub/styles.css';
app/user/styles.css

Javascript utilisateur

Là encore, tout comme pour les styles : la pages « index.html » de rnb-pub est un page HTML classique. Il est donc tout à fait possible d'injecter du code javascript utilisateur comme dans n'importe quelle autre page web :

import pub from '../rnb/pub/pub.js';

document.addEventListener('DOMContentLoaded', async () => {
    // do someting before rnb-pub
    // ....
    // run rnb-pub
    await pub();
    // do something after rnb-pub
    // ....
});
app/user/script.css

Attention évidemment : rnb-pub manipule tous les éléments de la page qui portent un attribut data-prop ; les modifier peut entrainer un dysfonctionnement du programme.

On peut néanmoins configurer rnb-pub à l'aide d'un objet PubOptions (voir le code source).

Formatter un champ de type date

Le format d'affichage des en-têtes de type date peut être personnalisé en fournissant son propre gestionnaire de format.

import pub from '../rnb/pub/pub.js';

const formatters = {
    'pubDate': new Intl.DateTimeFormat(undefined, {
        // format options
    })
};

document.addEventListener('DOMContentLoaded', async () => {
    await pub({formatters});
});
app/user/script.css

Convertisseur de syntaxe markdown

rnb-pub utilise un convertisseur de syntaxe markdown interne, propre au projet rnb-js. Si vous souhaitez utiliser votre propre convertisseur de syntaxe ou un convertisseur existant, il faudra définir la propriété « markdownConverter » de type MarkdownConverter :

import pub from '../rnb/pub/pub.js';

/**@type {MarkdownConverter}*/
const markdownConverter = async (content) => {
    // do conversion
    const element = document.createElement('p');
    element.textContent = content;
    return Promise.resolve(element);
};

document.addEventListener('DOMContentLoaded', async () => {
    await pub({markdownConverter});
});
app/user/script.css

À l'écoute d'événements

rnb-pub émet des événements que l'utilisateur peut écouter.

A écrire...

Pointer vers une page depuis l'exterieur

Les urls des pages

rnb-pub a été pensé pour fonctionner à la fois sur et en dehors d'un serveur web.Les urls d'une page sont donc un peu particulière.

Nous avons que pour créer un lien vers la page « /pages/page-01.md » par exemple, nous pouvions utiliser l'url « /pages/page-01 ». Il s'agit en fait d'une facilité d'écriture. La véritable url de la page serait en fait « ?r=/pages/page-01 » (« r » pour « ressource »).

En fait, rien ne vous interdit d'utiliser la notation « ?r=/pages/page-01 » pour l'url d'une page.

Cas d'une installation sur un serveur web

Si rnb-pub a été déployé sur un serveur web, il est joignable via une url sur ce serveur, disons par exemple « https://localhost/my-rnb-pub/ ».

Le lien vers la page « /pages/page-01 » sera alors :

https://localhost/my-rnb-pub/?r=/pages/page-01

Cas d'une installation locale

Avec un déploiement local, l'url d'accés à rnb-pub sera de la forme « file:///path/of/my-rnb-pub/ ».

Le lien vers la page « /pages/page-01 » sera alors :

file:///path/of/my-rnb-pub/index.html?r=/pages/page-01

Attention toutefois : l'utilisation de rnb-pub en installation locale ne peut se faire que dans un navigateur web spécialement configuré.

Licence

rnb-pub - Simple javascript Publisher Copyright (C) 2021 Rui Nibau, licensed using GPL V2.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2 of the License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.