Aller au contenu principal

Utiliser reSTructuredText dans Nikola

/images/previews/preview_restructuredtext.png

Le générateur de blog de Nikola utilise par défaut le format reStructuredText, comme alternative à Markdown. Il est bien sûr possible d'utiliser ce dernier mais reStructuredText est intéressant par de nombreux aspects.

Si ça vous intéresse, je vous explique comment installer Nikola.

Utilisation de reStructuredText

Si, reStructuredText est moins intuitif que Markdown et demande donc un peu plus de temps pour le maîtriser, il faut lui reconnaître qu'il permet au final de se simplifier la vie, et surtout d'avoir un texte plus propre et plus lisible, donc plus facile à corriger et maintenir. Les réflexes après l'apprentissages reST en mémoire facilement (désolé)

Vous pouvez, par exemple, référencer tous vos liens dans l'entête de votre article, et même utiliser des acronymes qui seront automatiquement remplacés dans votre texte par leur nom original...

Pour l'affichage des codes sources à intégrer, je vous recommande l'intégration du contenu d'un fichier. Placez vos fichiers sources avec vos codes dans le dossier "listings" et Nikola fera le reST (Hum...), par exemple avec l'appel ".. listing:: monfichier codage". Petite cerise libre, le lien vers le fichier source sera proposé.

Vraiment pratique pour revenir, sur une procédure détaillée, sans passer par l'article complet. Jugez plutôt avec ce petit exemple.

reST_exemple.rst (Source)

.. title: reSTructure de mon blog
.. slug: restructure-blog-echolib
.. date: 2021-10-30 17:27:19 UTC+02:00
.. tags: echolib, blog
.. author: echolib
.. category: A-Propos
.. description: Changement de blog, pour une version statique
.. type: text

.. |reST| replace:: reStructuredText
.. _Nikola: https://getnikola.com/
.. _`Nikola's handbook`: https://getnikola.com/handbook.html


Exemple d'écriture reST
=======================

Le moteur de blog de Nikola utilise par défaut le format |reST|.
Plus d'infos sur le `Nikola's handbook`_
Retour au premier titre : `Exemple d'écriture reST`_

.. image:: /galleries/echolib_reST_editor_geany.png
   :alt: Capture montrant l'auto-complétion dans Geany


Intégration de codes
--------------------
.. listing:: reST_exemple.rst rst


Lien Interne
------------
Mon :doc:`super article <slug-du-post>`

Avec un édtieur de texte spécialisé dans l'écriture de code, on peut même se concentrer davantage lors de ses frappes, grâce à l'auto-complétion.

Capture montrant l'auto-complétion dans Geany

Pour plus d'aides, Nikola propose un référenciel reST pour bien commencer, et pour comprendre ses nombreuses possibilités, allez voir la documentation officielle docutils. Sachez tout de même que certaines fonctionnalités ne sont pas prises en compte. Rien ne vous empêche d'essayer les exemples dans un article test en local.