Copier ce site

Vous écrivez ou avez un projet d’écriture ? L’essentiel du code source de ce site web est ouvert (licence MIT) et vous pouvez vous en emparer pour travailler vos propres projets littéraires. Le but initial de ce socle technique est en effet de servir de modèle de gestion de romans. Bien sûr, il est possible d’aller plus loin que ce que je décris dans ce tutoriel, si vous en avez les moyens. Vos capacités, vos limites.

Pourquoi j'ai créé ce modèle (mes motivations personnelles)

Je suis perfectionniste depuis toujours ; jusque-là, tout va bien — c’est faux, c’est l’enfer. Pour ne rien arranger, mon processus créatif est entaché par ce que je pense relever du trouble obsessionnel compulsif. S’il fallait décrire ce mal dont je souffre, je dirais qu’il m’oblige à donner plus de valeur à la forme qu’au fond. Non pas que je ne m’intéresse pas au contenu, au contraire ! Mais le contenant revêt — beaucoup — trop d’importance à mes yeux. Au point d’avoir des répercussions sur le contenu.

Je suis par exemple bien incapable de fermer les yeux sur…

  • Des espaces inégaux entre les mots (introduits par la justification) ;
  • Des fins de lignes en escalier (réglés par la justification) ;

… Et je peux être amené à (inter)changer certains mots voire à réécrire des paragraphes entiers jusqu’à obtenir un bloc de texte visuellement acceptable dans le contexte de visualisation courant. D’ailleurs, si vous lisez cette page avec un écran d’au moins 1366 pixels de large, prenez un peu le temps d’observer le contenu. Celui-ci ne vous apparaît-il pas étrangement harmonieux ?

C’est travaillé pour.

Idiot, n’est-ce pas ?
Je ne vous le fais pas dire.

Et je ne vous parle pas de mon combat pour choisir la fonte personnalisée qui me siéra, un temps seulement.

Alors ce modèle n’est pas magique. Il ne fera pas de vous des auteurs prolifiques. Il ne règle pas même mes problèmes, pas tous. Mais si vous vous considérez vous aussi perfectionnistes (et c’est plus souvent le cas qu’on ne le pense dans la création littéraire), il y a fort à parier pour que :

  1. Vous procrastiniez énormément. Ne pas faire est en effet le meilleur moyen d’échapper à l’échec.
  2. L’ampleur de la tâche vous décourage très vite.

Pour ce deuxième point, raisonner avec un modèle tel que celui-ci commence à faire sens. Le meilleur moyen pour un perfectionniste d’atteindre un objectif semble être de le diviser. Un perfectionniste qui d’emblée approche la création littéraire comme un seul bloc échouera. Si en revanche il travaille séparément sur chaque personnage, lieu ou arc narratif, il se donne les moyens de parvenir à ses fins, s’agissant de tâches plus modestes qui, de surcroît, lui permettront d’apprécier sa progression.

C’est en tout cas ce que j’ai expérimenté par moi-même.

Parmi les principales fonctionnalités du modèle à date :

Envie d’essayer ?
C’est parti.

Démarrage rapide

Pour tirer parti de ce modèle, il suffit d’en respecter les conventions. En développement, le fait de suivre les conventions fait que vous n’aurez pas vraiment de code à écrire par vous-même pour que cela fonctionne. Rien ne vous empêche en revanche d’aller plus loin.

1. Ce que vous devriez savoir faire avant d’aller plus loin

Avant de perdre votre temps, et parce que rien de tout ceci ne sera expliqué ici, assurez-vous de savoir :

  1. Télécharger ou cloner ce projet depuis GitLab, à l’adresse https://gitlab.com/julien.wilhelm/kitami.awebsome.fr.
  2. Installer Ruby, le langage sur lequel repose Jekkyl, le générateur de sites statiques derrière ce modèle ;
  3. Rédiger du contenu en Markdown, le format utilisé pour mettre en forme vos contenus ;
  4. Respecter la syntaxe YAML, pour la configuration principale et les en-têtes de documents (front matter) ;
  5. Utiliser la ligne de commande pour installer les dépendances requises et démarrer les phases de développement (bundle exec jekyll serve --livereload --port 4001) et de production (bundle exec jekyll build).
  6. Héberger un service numérique, si votre intention est de le partager.

2. Structure type du modèle

Il est utile de comprendre le rôle des dossiers et fichiers du modèle, listés ici de manière exhaustive :

Voici maintenant ce que vous allez vraiment manipuler, idéalement dans cet ordre :

  1. _config.yaml, pour personnaliser la solution au démarrage. La configuration de différentes options y est centralisée et documentée pour ne pas avoir à plonger dans le cœur du code source.
  2. assets/images, pour y remplacer le favicon qui apparaît dans l’onglet du navigateur web, mais aussi l’image de profil située en bas à gauche de l’écran (se reporter au fichier ci-dessus pour en savoir plus).
  3. _pages, pour éditer du contenu.
  4. index.md, pour éditer le contenu de la page d’accueil.

Vous allez donc très vite passer du temps dans le dossier “_pages” pour travailler vos romans.

(en tout cas, c’est l’objectif)

3. Le dossier “_pages/projets” et les niveaux de pages

Le dossier “_pages/projets” contient tous vos romans.

En voici la structure type telle que je la propose par défaut :

Cette structure permet de déployer 3 types de pages :

Pour assimiler au mieux cette structure, explorez le dossier de démonstration. Appropriez-le-vous en ajoutant des pages ou en supprimant celles qui ne vous semblent pas pertinentes.

4. Les métadonnées du front matter

Pour que la magie opère, il reste à traiter la question du front matter. Ce dernier décrit en en-tête de tous les fichiers markdown des métadonnées sur lesquelles le socle technique va s’appuyer.

Il existe 6 métadonnées possibles utilisées de la façon suivante :

Bon à savoir : l’ordre dans lequel figurent ces métadonnées est sans incidence sur le comportement du socle technique.

Pour une page de niveau 1

Prenons l’exemple du front matter de la page /_pages/projets/demo-gestion-de-roman/index.md :

---
project: "Démo : gestion de roman"
title: "Démo : gestion de roman"
license: "MIT"
---

Celui-ci précise :

Envie d’une page d’accueil plus poussée ? Désactivez la liste automatique de base en ajoutant listPages: false dans le front matter de ces pages de niveau 1 puis insérez le modèle de liste étendu en ajoutant l’instruction {% include lists/landing-list-extended.html %} dans le corps.

Pour une page de niveau 2

Prenons l’exemple du front matter de la page /_pages/projets/demo-gestion-de-roman/2-personnages/index.md :

---
project: "Démo : gestion de roman"
section: "2. Personnages"
title: "2. Personnages"
license: "MIT"
---

Celui-ci précise :

Pour une page de niveau 3

Prenons l’exemple du front matter de la page /_pages/projets/demo-gestion-de-roman/2-personnages/jean.md :

---
project: "Démo : gestion de roman"
section: "2. Personnages"
title: "Jean"
license: "MIT"
completed: true
---

Celui-ci précise :

Guide de contribution spécifique

Avant d’entrer dans le vif du sujet, je me dois de rappeler que ce projet s’inscrit dans une démarche d’écoconception et vise à être accessible. Mais si la technique (ce que je vous donne) est une chose, je ne peux évidemment pas endosser la responsabilité de la contribution (ce que vous en faites). Je vous invite donc à vous documenter sur ces deux thématiques fortes du Numérique Responsable pour faire de votre mieux.

Utiliser le bon chemin pour un lien hypertexte manuel

Si vous utilisez un éditeur de code intelligent, il est probable qu’il ait des fonctionnalités d’autocomplétion sur les chemins de fichiers. Au moment d’insérer un lien en markdown, vous pouvez obtenir un chemin tel que :

# Chemin vers le fichier
[Jean](/_pages/projets/demo-gestion-de-roman/2-personnages/jean.md)

Ce type de chemin doit être corrigé pour garantir que tout fonctionne correctement, y compris en production :

# Chemin vers le contenu de la page
[Jean](/pages/projets/demo-gestion-de-roman/2-personnages/jean.html#main)

Dans le détail :

  1. “_pages” devient “pages”, car nous ne souhaitons pas pointer vers le fichier physique, mais vers la page générée ;
  2. “.md” devient “.html”, car nous devons cibler un document HTML, et non pas du markdown, qui est notre source ;
  3. “#main” est ajouté, car nous souhaitons atteindre le contenu de la page. C’est particulièrement utile sur mobile, où la navigation se situe en partie supérieure de l’interface, car cela épargne à l’utilisateur de devoir défiler jusqu’au contenu au moindre changement de page.

Éviter les conflits entre liens hypertextes automatiques et manuels

La fonctionnalité d’insertion automatique de liens hypertextes peut entrer en conflit avec certains liens que vous aurez créés manuellement. Pour éviter cela, deux recommandations simples :

  1. Limitez l’insertion automatique de liens hypertextes aux seuls noms de personnages et de lieux.
  2. Ne créez jamais de liens hypertextes dont le libellé contient un nom remplacé automatiquement.

Insérer un spoiler (code HTML)

Puisque la syntaxe markdown ne permet pas d’insérer l’élément details requis pour les spoilers, il va falloir écrire un peu de HTML.

Voici le code à adapter à vos besoins pour y parvenir :

<details markdown="0">
<summary>intitulé du spoiler</summary>
<div markdown="1">
contenu du spoiler
</div> 
</details>

Et un cas d’usage basique…

<details markdown="0">
<summary>Spoiler : que cache Jean dans sa poche ?</summary>
<div markdown="1">
Une balle rebondissante !
</div> 
</details>

… Avec son rendu, à révéler au clic :

Spoiler : que cache Jean dans sa poche ?

Une balle rebondissante !

Insérer une image responsive (code Liquid)

Ajouter une image en markdown, c’est facile. Intégrer une image tenant compte du contexte (mobile, tablette, ordinateur) et du parcours de l’utilisateur, c’est en revanche une autre paire de manches. Si le sujet vous intéresse (il devrait), voici la meilleure manière de procéder, tout simplement :

{% include images/full-width-image.html imgName="..." imgFormat="..." imgAlt="" imgLoading="lazy" %}

Cette instruction à adapter et à coller dans le fichier markdown où vous souhaitez insérer l’image fait appel à un gabarit pensé pour l’interface utilisateur de ce projet.

Dans le détail :

Pour que cela fonctionne, vous devez :

À titre d’exemple, voici l’instruction pour l’image au sommet de cette page…

{% include images/full-width-image.html imgName="apercu-documentation" imgFormat="webp" imgAlt="" imgLoading="eager" %}

…Et le code qui en découle :

<picture>
    <source srcset="./apercu-documentation-750.webp" media="(min-width: 1280px)" type="image/webp">
    <source srcset="./apercu-documentation-500.webp 1x, ./apercu-documentation-1000.webp 2x" media="(min-width: 960px)" type="image/webp">
    <source srcset="./apercu-documentation-750.webp" media="(min-width: 840px)" type="image/webp">
    <source srcset="./apercu-documentation-500.webp 1x, ./apercu-documentation-1000.webp 2x" media="(min-width: 620px)" type="image/webp">
    <source srcset="./apercu-documentation-250.webp 1x, ./apercu-documentation-500.webp 2x, ./apercu-documentation-750.webp 3x" type="image/webp">
    <img src="./apercu-documentation-250.webp" alt="" loading="eager">
</picture>

Protéger l’accès à certaines pages (code Apache)

Vous l’aurez constaté en creusant un peu : vous n’avez pas accès à tous les contenus de ce site. Autant je partage volontiers le code source de la solution technique, autant je ne suis pas (encore) prêt à ouvrir tout ce que je produis. Mes idées, je les chéris, et j’ai des projets pour elle.

Alors si vous préférez vous aussi protéger vos œuvres, c’est OK.

À ce sujet :

Pour en revenir au sujet initial, il est tout à fait possible d’exiger de l’utilisateur qu’il s’authentifie avant d’accéder au contenu. Par exemple, si vous déployez votre projet sur un serveur Apache, adaptez le code suivant dans un fichier “.htaccess” :

ErrorDocument 401 "Authorisation Required"
AuthType Basic
AuthName "L'accès à ce répertoire est protégé, veuillez vous identifier"
AuthUserFile "/chemin/complet/vers/.htpasswd"
Require user nom_utilisateur
Satisfy All

Stockez ensuite ce fichier dans chaque dossier à protéger.

Vous aurez aussi besoin de générer le fichier “.htpasswd” vers lequel pointe le fichier “.htaccess”. Quelques recherches sur le Web vous permettront de connaître la procédure exacte.