Orgmode et Jekyll

Fri, 1 May, 2015 (900 Words)

Un peu plus d'un an..

.. que je n'ai rien posté ici. Le temps passe bien vite, mais c'est plutôt une bonne chose. Je crois que quelque chose me manquait pour poster ici plus souvent.

Au niveau de mes points d'entrées sur le web, je compte remettre un peu en route la partie blog de ce site et tourner shortbrain.org (ou autre) en un site plus "documentation" en me basant sur mes notes (powered by org-mode). Je me suis également remis à Gnu Emacs et oh god qu'est-ce que c'est bon :-D.

C'est ce que j'écrivais il y a un an, et effectivement c'est toujours aussi bon ;-D. J'ai commencé à utiliser org-mode de manière assez intensive, pour mettre en place mon personal kanban mais également pour prendre mes notes. Et plus je l'utilise, plus j'ai du mal m'en passer et à aller dans mon dossier hébergeant ce site pour y écrire en Markdown. Il me fallait donc trouver une astuce pour convertir certaines notes en post pour Jekyll. C'est maintenant chose faite (après 6 mois dans ma TODO-list…), et voici comment je m'en sors.

L'idée générale est assez simple :

  1. Utiliser un dossier particulier pour les notes destiné à ce blog
  2. Exporter, au format html, ces notes dans le bon dossier (_posts)
  3. … et c'est tout en fait :) — c'était pas ben compliqué !

Les fichiers org

Tous mes fichiers org-mode sont dans un ensemble de dossiers bien particulier — cela n'a pas grand chose d'important à faire ici, mais ça permet de suivre la configuration qui suit. Il s'agit du dossier ~/desktop/org/, et de ces fils : todos pour ce que je dois faire et notes pour ma prise de note. Dans notes on trouve donc des dossiers et en particulier un qui se nomme vdf (pour Vincent.Demeester.Fr).

La seule différence que les fichiers .org ont dans ce dossier par rapport aux autres, c'est le début du fichier. En effet, Jekyll a besoin d'une entête en YAML pour le layout, les tags, la catégorie et plein d'autres trucs. Le fichier org de ce billet ressemble à ça par example : 

#+BEGIN_HTML
---
layout: post
category: developement
tags: jekyll blog emacs orgmode html
lang: fr
---
#+END_HTML
* Un peu plus d'un an..

.. que je n'ai rien posté ici. Le temps passe bien vite, mais c'est plutôt une bonne chose. Je crois que quelque chose me manquait pour poster ici.

[…]

Les utilisateurs de Jekyll reconnaitront les --- et le format du header. #+BEGIN_HTML et #+END_HTML sont là pour dire à org-mode d'exporter un bloc en HTML sans l'interpréter — c'est une façon de mettre du HTML dans un document org si on peut pas faire ce qu'on veut avec le markup. Ici ça nous permet d'exporter tel quel le header de Jekyll en haut du HTML généré, pratique !

Configuration de org-mode

Il reste maintenant à configurer le projet de publication (publishing project) dans Emacs. Je vais mettre ici juste la partie intéressante, donc pour plus d'information sur comment publier des fichiers org-mode avec Emacs, c'est par ici pour un tutoriel (j'adore worg soit dit en passant :P).

L'idée c'est de définir un projet avec plusieurs components, un pour les fichiers org, un pour les fichiers css et un pour les assets (images, vidéos, …). On souhaite également ne pas générer de table des matières (TOC) et ne génerer que le body (pas de <head>, …). Et ça se présente comme suit. 

;; Variables
(setq vdf-base-directory "~/desktop/org/notes/vdf/"
      vdf-site-directory "~/src/github/vdemeester/vdemeester.github.com"
      vdf-publishing-directory (expand-file-name "_posts" vdf-site-directory)
      vdf-css-publishing-directory (expand-file-name "css" vdf-site-directory)
      vdf-assets-publishing-directory (expand-file-name "assets" vdf-site-directory))

;; Project
(setq org-publish-project-alist
      `(("vdf-notes"
         :base-directory ,vdf-base-directory
         :base-extension "org"
         :publishing-directory ,vdf-publishing-directory
         :exclude "FIXME"
         :section-numbers nil
         :with-toc nil
         :with-drawers t
         :htmlized-source t
         :publishing-function org-html-publish-to-html
         :headline-levels 4
         :body-only t)
        ("vdf-static-css"
         :base-directory ,vdf-base-directory
         :base-extension "css"
         :publishing-directory ,vdf-css-publishing-directory
         :recursive t
         :publishing-function org-publish-attachment
         )
        ("vdf-static-assets"
         :base-directory ,vdf-base-directory
         :base-extension "png\\|jpg\\|gif\\|pdf\\|mp3\\|ogg"
         :publishing-directory ,vdf-assets-publishing-directory
         :recursive t
         :publishing-function org-publish-attachment
         )
        ("vdf" :components ("vdf-notes" "vdf-static-css" "vdf-static-assets"))
        ))

J'utilise des variables, c'est pas indispensable mais c'est plus pratique. Il y a trois components, chacun définit les fichiers qu'il traite grâce à :base-extension. Intéressons-nous surtout à vdf-notes puisque c'est celui qui nous sort les fichiers HTML à partir des fichiers org. On se passe de table des matières grâce à :with-toc nil, on ne génère que le body grâce à :body-only t et on évite les numéros de sections avec :section-numbers nil. Le bonus vient avec :htmlized-source t puisque du coup, les parties sources (entre #+BEGIN_SRC et #+END_SRC) sont exportés avec les mêmes couleurs que j'ai dans ma configuration Emacs (avec les rainbow-identifiers, voir ce post là également).

Il ne reste plus qu'à publier le projet quand on le souhaite avec org-publish — je vous laisse lire la documentation pour savoir comment on fait.

Et c'est tout bon. Un petit bundle exec jekyll serve --watch pour voir le rendu — et quand on est content on commit. Et c'est la fête \o/.

C'est tout pour le moment, la fréquence des billets de ce blog devrait s'incrémenter un peu maintenant.