Création du site

Docusaurus.io

Voici les étapes que j'ai suivies pour créer ce blog.

Utiliser Docusaurus​

Comme j'aime vraiment la simplicité de Docker, je ne vais pas installer Node.js sur ma machine mais utiliser l'image Docker officielle. Cet article montre l'approche brute avec docker run ; si vous préférez un Dockerfile et un compose.yaml prêts à l'emploi, allez voir Exécuter Docusaurus avec Docker.

docker run --rm --name blog --user $UID:$GID -it -v ${PWD}/:/project -w /project node /bin/bash
▋

L'instruction ci-dessus va télécharger Node.js (la dernière version) sur ma machine s'il n'est pas déjà présent et créer une instance en cours d'exécution (appelée un container). Le flag --user $UID:$GID permet de démarrer le container avec les mêmes identifiants que les miens en local (c.-à-d. réutiliser mon utilisateur Unix local christophe pour que les fichiers/dossiers créés dans le container appartiennent à mon utilisateur local).

L'argument de ligne de commande -v ${PWD}/:/project va partager mon dossier courant sur mon ordinateur avec le container : le dossier /project dans le container sera mon dossier courant sur mon ordinateur.

Et enfin, je lance un shell interactif puisque j'ai indiqué /bin/bash comme point d'entrée.

Maintenant que j'ai un prompt dans le container, je vais créer mon blog avec Docusaurus (comme expliqué dans la documentation officielle).

$ npx create-docusaurus@latest blog classic --javascript▋

Après un bon moment, le dossier blog est créé et je peux jeter un œil à son contenu :

L'étape d'installation est terminée ; je vais quitter le container et revenir sur mon ordinateur. Pour cela, depuis la console Docker, je tape simplement exit.

Lancer le site web​

De retour sur mon ordinateur, je vais aller dans mon dossier blog (cd blog) et relancer la commande Docker, mais cette fois avec le paramètre supplémentaire -p 3000:3000. Ce paramètre va exposer le port 3000 du container vers ma machine pour que je puisse voir le site en surfant sur http://localhost:3000.

Plutôt que de lancer une session shell interactive, je préfère exécuter /bin/bash -c "npx docusaurus start" pour lancer le watcher de Docusaurus et servir mes fichiers :

▋

Après quelques secondes, le container est prêt et je surfe sur mon site en allant sur http://localhost:3000.

Quelques réglages​

Par défaut (avec l'installation standard), Docusaurus va créer le squelette d'un site web avec deux entrées principales : un blog et un tutoriel.

Pour rester simple, je ne garde que le blog et supprime la partie tutoriel. Pour cela, j'ai suivi cet article officiel : https://docusaurus.io/docs/blog#blog-only-mode.

Maintenant, je peux supprimer le dossier /docs de mon répertoire blog :

Je vais aussi apporter quelques modifications à des fichiers comme docusaurus.config.js ou blog/authors.yml pour coller à mes besoins.

Fichier docusaurus.config.js​

En mettant hideOnScroll à true, la barre de navigation sera masquée quand l'utilisateur défile vers le bas mais réapparaîtra dès qu'il défile vers le haut. L'idée est de donner plus de place à l'écran pour le contenu.

export default {?
  themeConfig: {
    navbar: {
        // auto-hide the navbar when the user will scroll down, show again when scroll up
        hideOnScroll: true,?
    },
  },
};

Définir l'image par défaut pour les réseaux sociaux :

export default {?
  themeConfig: {
    // Default image when sharing a post on social media
    image: 'img/social-card.jpg',?
  },
};

Écrire mon premier article​

Avec mon éditeur préféré (vscode), j'ouvre le site de mon blog (je tape juste code . dans ma console Linux pour ouvrir mon projet blog).

Maintenant, dans le répertoire /blog, je crée un nouveau dossier appelé 2023-11-02-site-creation et j'y crée le fichier index.md.

Dans le chapitre précédent, npx a été exécuté avec la commande docker run --rm -it --name blog --user $UID:$GID -v ${PWD}/:/project -w /project -p 3000:3000 node /bin/bash -c "npx docusaurus start --host 0.0.0.0" donc, toute modification faite au blog sera immédiatement synchronisée avec Docker : je n'ai qu'à sauvegarder mon article et npx rechargera mon site ; très simple et pratique.

Utiliser quelques mises en page​

Docusaurus supporte des tags Markdown spéciaux appelés admonition (voir https://docusaurus.io/docs/markdown-features/admonitions).

Par exemple, pour afficher un paragraphe comme une astuce, comme ci-dessous, il suffit d'utiliser cette syntaxe :

:::tip
Some **content** with _Markdown_ `syntax`.
:::

Pour obtenir la liste complète des fonctionnalités supportées, voir Markdown Features.

Ajouter des plugins​

Moteur de recherche​

https://github.com/cmfcmf/docusaurus-search-local

La fonctionnalité de moteur de recherche a été ajoutée en suivant cet article de blog : https://yoandev.co/une-documentation-avec-docusaurus-et-gitlab-pages/#bonus--ajoutons-un-moteur-de-recherche

Ajouté en lançant yarn add @cmfcmf/docusaurus-search-local dans le container Docker (ouvert avec make bash).

Support de PHP et bash dans prism​

https://www.npmjs.com/package/@docusaurus/theme-classic

Ajouté en lançant yarn swizzle @docusaurus/theme-classic prism-include-languages dans le container Docker (ouvert avec make bash). Plus de détails sur Supported Languages.

Générateur de sitemap​

https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-sitemap

Ajouté en lançant yarn add @docusaurus/plugin-sitemap dans le container Docker (ouvert avec make bash).

Après l'ajout, j'ai aussi créé manuellement le fichier static/robots.txt avec ce contenu :

User-Agent: *?
Sitemap: https://www.avonture.be/sitemap.xml?
Disallow: /*index.xml$?
Disallow: /index.json
Disallow: /search/index.json

Plugins d'images​

https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-ideal-image

Ajouté en lançant yarn add @docusaurus/plugin-ideal-image dans le container Docker (ouvert avec make bash). Plus de détails sur Supported Languages.

https://www.npmjs.com/package/docusaurus-plugin-image-zoom

Ajouté en lançant yarn add docusaurus-plugin-image-zoom dans le container Docker (ouvert avec make bash).

Ajouter une zone de commentaires​

How to add Giscus comments to Docusaurus

Ajout de Giscus pour permettre les commentaires et les retours.

Pousser sur Github​

Sur Github.com, j'ai créé un nouveau repository appelé blog (https://github.com/cavo789/blog). Une fois cela fait, retour à ma console et je lance quelques commandes git :

$ git init
...
$ git add .
...
$ git commit -m "Initial commit"
...
$ git remote add origin git@github.com:cavo789/blog
...
$ git push -u origin master
...
▋

Cela fait, j'ai donc poussé mes fichiers sur Github comme prévu par Docusaurus : par exemple, /node_modules ne fait pas partie de mon repo ; ce qui est très bien puisque nous créerons ce dossier plus tard en lançant une commande npx sur le serveur web où le site sera hébergé.

Construire la version statique du blog​

Pour construire les pages statiques, je lance docker run --rm -it --user $UID:$GID -v ${PWD}/:/project -w /project node /bin/bash -c "yarn build".

Cela va créer/mettre à jour le dossier /build avec une version fraîche du site.

L'étape suivante est de démarrer mon client FTP (qui est WinSCP) et de copier mon dossier local /blog/build vers mon site distant. Pour n'envoyer que les fichiers réellement modifiés, voir WinSCP - Synchroniser l'host et le serveur distant.

Aujourd'hui, je ne le fais plus à la main : le site est déployé automatiquement, comme expliqué dans GitHub - Utiliser les Actions pour déployer ce blog.

Ajouter withcabin pour des stats conformes au RGPD​

En ajoutant les lignes ci-dessous au docusaurus.config.js comme nœud enfant de const config, j'injecte un script dans la partie body. Cela permettra ensuite d'avoir des stats conformes au RGPD sur https://withcabin.com/.

scripts: [
  {
    src: 'https://scripts.withcabin.com/hello.js',
    async: true,?
    defer: true,?
  },
],

Note : le script n'est injecté dans les pages qu'après un yarn build, c'est-à-dire quand le site statique est généré ; pas pendant un yarn watch.