Dans le chapitre précédent, nous avons vu comment écrire du contenu - articles et pages - sur notre blog à l’aide du markdown. Dans ce nouveau chapitre, nous allons voir comment utiliser les principaux plugins fournis avec Octopress afin d’enrichir le contenu des articles et des pages.

Plan

• Créer un blog statique avec Octopress (1/7) : à la découverte d’Octopress
• Créer un blog statique avec Octopress (2/7) : installation et configuration
• Créer un blog statique avec Octopress (3/7) : écrire du contenu - les bases
• Créer un blog statique avec Octopress (4/7) : écrire du contenu - les plugins
• Créer un blog statique avec Octopress (5/7) : un blog social
• Créer un blog statique avec Octopress (6/7) : utiliser un thème téléchargé
• Créer un blog statique avec Octopress (7/7) : personnaliser l’apparence de son blog

Les médias

Les images

Dans le chapitre précédent, nous avons vu comment ajouter des images dans nos articles et pages à l’aide du markdown. Pour rappel, voici comment faire :

![photo d'hawai](http://www.mon-super-site.fr/hawai.png "Photo prise à hawai")

On écrit le caractère ! suivi du texte alternatif de l’image entre crochets lui-même suivi du lien de l’image entre parenthèses et d’un éventuel titre.

Avec Octopress, il est possible d’utiliser le plugin Image Tag permettant d’accroitre les possibilités au moment d’inclure une image en spécifiant, par exemple, sa taille.

Les plugins, dans Octopress, ont sensiblement tous la même syntaxe, à savoir que l’on écrit entre accolades et pourcentages l’identifiant du plugin que l’on souhaite utiliser, suivi des différents paramètres qu’il accepte.

Voyons immédiatement la syntaxe du plugin Image Tag dont le code est img :

{% img [classe CSS] /chemin/de/limage [largeur] [hauteur] [Titre de l'image [Texte alternatif]] %}

Tentons alors d’intégrer le markdown suivant dans un article ou une page :

{% img http://static.siteduzero.com/prod/visuels/bureau.jpg 400 %}

{% img http://static.siteduzero.com/prod/visuels/bureau.jpg 200 %}

Générez le blog et prévisualisez l’article ou la page dans laquelle vous venez d’inclure le code. Vous devriez y apercevoir deux images avec une largeur différente :

Je vous propose maintenant de voir un exemple utilisant les classes CSS right et left qui sont deux classes préexistantes dans Octopress. Comme leurs noms le suggèrent, ces classes CSS permettent de définir des éléments flottants à droite ou à gauche. Soit le markdown suivant dans lequel on agence les éléments de la manière suivante :

• une image flottante à gauche ;
• deux paragraphes ;
• une image flottante à droite ;
• deux paragraphes.

{% img left http://static.siteduzero.com/prod/visuels/bureau.jpg 400 %}

Soleo saepe ante oculos ponere, idque libenter crebris usurpare sermonibus, omnis nostrorum imperatorum, omnis exterarum gentium potentissimorumque populorum, omnis clarissimorum regum res gestas, cum tuis nec contentionum magnitudine nec numero proeliorum nec varietate regionum nec celeritate conficiendi nec dissimilitudine bellorum posse conferri; nec vero disiunctissimas terras citius passibus cuiusquam potuisse peragrari, quam tuis non dicam cursibus, sed victoriis lustratae sunt.

Illud autem non dubitatur quod cum esset aliquando virtutum omnium domicilium Roma, ingenuos advenas plerique nobilium, ut Homerici bacarum suavitate Lotophagi, humanitatis multiformibus officiis retentabant.

{% img right http://static.siteduzero.com/prod/visuels/bureau.jpg 400 %}

Mensarum enim voragines et varias voluptatum inlecebras, ne longius progrediar, praetermitto illuc transiturus quod quidam per ampla spatia urbis subversasque silices sine periculi metu properantes equos velut publicos signatis quod dicitur calceis agitant, familiarium agmina tamquam praedatorios globos post terga trahentes ne Sannione quidem, ut ait comicus, domi relicto. quos imitatae matronae complures opertis capitibus et basternis per latera civitatis cuncta discurrunt.

Quam quidem partem accusationis admiratus sum et moleste tuli potissimum esse Atratino datam. Neque enim decebat neque aetas illa postulabat neque, id quod animadvertere poteratis, pudor patiebatur optimi adulescentis in tali illum oratione versari. Vellem aliquis ex vobis robustioribus hunc male dicendi locum suscepisset; aliquanto liberius et fortius et magis more nostro refutaremus istam male dicendi licentiam. Tecum, Atratine, agam lenius, quod et pudor tuus moderatur orationi meae et meum erga te parentemque tuum beneficium tueri debeo.

Générez le blog et prévisualisez l’article ou la page dans laquelle vous venez d’inclure le code. Vous devriez y apercevoir deux images avec une position différente :

Les vidéos

Nous venons de le voir, Octopress nous offre un puissant plugin pour gérer l’affichage des images. Les vidéos ne sont pas en reste grâce au plugin HTML5Video Tag.

Je vous le disais précédemment, tous les plugins utilisés dans Octopress ont sensiblement la même syntaxe. Ainsi, le plugin vidéo possède une syntaxe très proche de celle du plugin image :

{% video chemin/de/la/video [largeur hauteur] [chemin/de/lapercu] %}

Je vous propose d’intégrer notre première vidéo via le code markdown suivant :

{% video http://mirrorblender.top-ix.org/peach/bigbuckbunny_movies/big_buck_bunny_1080p_stereo.ogg 854 480 http://static.siteduzero.com/prod/visuels/bureau.jpg %}

Générez le blog et prévisualisez l’article ou la page dans laquelle vous venez d’inclure le code. Vous devriez y apercevoir un lecteur vidéo avec la miniature que nous avons indiquée (qui soit dit en passant n’a rien à voir avec le contenu réel de vidéo) :

Cliquez sur le bouton de lecture pour lancer la vidéo :

Le code

Dans le chapitre précédent, nous avons vu qu’il était possible d’intégrer du code via markdown soit via l’utilisation du caractère `, soit via la simple utilisation de l’indentation. Mais Octopress permet d’aller encore plus loin grâce notamment à deux plugins :

• Backtick Code Block
• Code Block

Le plugin Backtick Code Block

Ce premier plugin utilise une syntaxe proche de la syntaxe markdown permettant d’écrire du code inline à l’exception près que le code n’est pas entouré d’un mais trois `. Voici sa syntaxe complète :

``` [langage] [titre] [url] [texte_du_lien] [linenos:false] [start:numéro_de_ligne] [mark:numéro_de_ligne]
écrire le code ici
```

Revenons plus en détails sur les différents éléments qui composent la syntaxe de ce plugin :

• langage permet de préciser le langage du code et ainsi adapter la coloration syntaxique ;
• titre permet de préciser un titre au bloc de code ;
• url et texte_du_lien permettent de lier le bloc de code à une URL pour par exemple rediriger l’utilisateur sur internet ou lui proposer de télécharger le fichier contenant le code source ;
• linenos:false permet de ne pas afficher la numérotation des lignes ;
• start permet de préciser le numéro de la première ligne du code à afficher ;
• mark permet de préciser les lignes à mettre en avant en les surlignant.

Avant de voir quelques exemples, revenons quelques instants sur le paramètre mark. Ce paramètre permet de préciser autant de lignes que vous le souhaitez. Par exemple, si l’on souhaite mettre en avant la ligne 24, voici ce que l’on doit écrire :

mark:24

Maintenant, si l’on souhaite mettre en avant les lignes 24, 27 et 58, voici ce que l’on doit écrire :

mark:24,27,58

Maintenant, si l’on souhaite mettre en avant les lignes 1 à 12, voici ce que l’on doit écrire :

mark:1-12

Finalement, si l’on souhaite mettre en avant la ligne 2 et les lignes 5 à 7, voici ce que l’on doit écrire :

mark:2,5-7

Si le plugin Backtick Code Block ne permet pas la coloration syntaxique de tous les langages existants, il en connaît tout de même plus de 100, ce qui devrait, j’en suis sûr, faire votre bonheur. Tous les citer ici n’aurait pas vraiment de sens, c’est pourquoi je vous invite à jeter un coup d’oeil à la documentation officielle afin de vérifier que le langage que vous souhaitez utiliser est supporté.

Il est maintenant temps de voir un exemple. Soit le code markdown suivant à placer dans un article ou une page Octopress :

``` java Java http://fr.wikipedia.org/wiki/Java_%28langage%29 Wikipedia
final String test = "test";
System.out.println(test);
```

Décryptons ensemble ce petit code markdown. Le langage utilisé est le Java comme en témoigne le tout premier mot clef utilisé. Le bloc de code aura pour titre le mot Java et proposera un lien vers une page Wikipedia sous le libellé Wikipedia.

Générer votre blog, prévisualisez le et rendez-vous sur l’article ou la page qui contient le code. Vous devriez normalement y voir le contenu suivant s’afficher :

Le plugin Code Block

Passons maintenant à l’étude du plugin Code Block. Ce plugin utilise une syntaxe proche de celle des plugins images et vidéos puisqu’il utilise des accolades. Voici sa syntaxe complète :

{% codeblock [lang:langage] [titre] [url] [texte_du_lien] [start:numéro_de_ligne] [mark:numéro_de_ligne] [linenos:false] %}
écrire le code ici
{% endcodeblock %}

Comme vous pouvez le constater, les différents paramètres sont semblables à ceux utilisés dans le plugin Backtick Code Block, à savoir :

• langage permet de préciser le langage du code et ainsi adapter la coloration syntaxique ;
• titre permet de préciser un titre au bloc de code ;
• url et texte_du_lien permettent de lier le bloc de code à une URL pour par exemple rediriger l’utilisateur sur internet ou lui proposer de télécharger le fichier contenant le code source ;
• linenos:false permet de ne pas afficher la numérotation des lignes ;
• start permet de préciser le numéro de la première ligne du code à afficher ;
• mark permet de préciser les lignes à mettre en avant en les surlignant.

Une nouvelle fois, pour vérifier que le langage de programmation que vous souhaitez utiliser est supporté par le plugin, je vous invite à visiter la documentation officielle. Finalement, concernant l’utilisation du paramètre mark, je vous invite à vous reporter à la partie de ce tutoriel traitant du plugin Backtick Code Block dans lequel tout est expliqué.

Voyons alors le plugin en plein action. Soit le code markdown suivant à placer dans un article ou une page Octopress :

{% codeblock lang:java Java http://fr.wikipedia.org/wiki/Java_%28langage%29 Wikipedia start:52 %}
final String test = "test";
System.out.println(test);
{% endcodeblock %}

Decryptons ensemble ce petit code markdown. Le langage utilisé est le Java, le bloc de code aura pour titre le mot Java et proposera un lien vers une page Wikipedia sous le libellé Wikipedia.

Générer votre blog, prévisualisez le et rendez-vous sur l’article ou la page qui contient le code. Vous devriez normalement y voir le contenu suivant s’afficher :

D’autres plugins ?

Comme je vous le disais plus tôt dans ce tutoriel, il est possible d’utiliser de très nombreux plugins. Ainsi, nous venons d’en voir deux permettant de formatter du code, mais sachez qu’il en existe d’autres comme par exemple :

• Gist Tag qui permet d’afficher le code d’un fichier d’un gist Github ;
• Include Code qui permet d’afficher du code et dont l’utilisation est similaire au plugin Code Block.

Des problèmes sous Windows ?

Si vous rencontrez cette erreur, pas de panique, vous êtes sous Windows ! :p Plus sérieusement, le problème vient du fait que tous les outils ne sont sans doute pas à jour, voir absents ! Plusieurs pistes doivent être explorées.

La première piste consiste à mettre à jour la bibliothèque rdiscount. Cette bibliothèque est utilisée par Octopress pour traduire les documents markdown en documents HTML. Pour mettre à jour rdiscount, rendez-vous dans l’invite de commandes et saisisez la commande suivante :

 gem update rdiscount

Une fois la mise à jour terminée, générez votre blog puis prévisualisez le. Tout devrait être rentré dans l’ordre. Si ce n’est pas le cas, passons à la seconde piste qui consiste à installer Python. En effet, les plugins Backtick Code Block et Code Block utilisent Pygments, une bibliothèque Pyhton.

La première étape consiste donc à télécharger Python sur le site officiel. Dans le cadre de ce tutoriel, nous allons télécharger la version 2.7. Lancer l’installation :

Une fois l’installation terminée, ajouter le dossier d’installation de Python au Path Windows. Regénérez votre blog et prévisualisez le. Vous devriez y voir du contenu s’y afficher.

Si ça ne fonctionne toujours pas, nous allons explorer une ultime piste : l’installation d’une version spécifique du gem pygments.rb. Pour ce faire, utiliser la commande suivante :

 gem install pygments.rb --version "=0.5.0"

J’espère pour vous que maintenant vous voyez le contenu de votre blog s’afficher sur votre écran.

Les citations

Jusqu’à maintenant, nous venons de voir en détail divers plugins pour gérer plus facilement l’affichage d’images, de vidéos ou encore de code. Je vous propose maintenant de nous pencher sur deux plugins permettant de gérer les citations :

• Block Quote
• Pull Quote

Le plugin Block Quote

Ce plugin utilise une syntaxe proche de celle de la plupart des plugins que nous avons étudiée jusqu’à maintenant :

{% blockquote [auteur[, source]] [lien] [titre_du_lien] %}
écrire la citation ici
{% endblockquote %}

Comme vous pouvez le constater, les différents paramètres sont tous entre crochets et donc tous facultatifs. Le nom des paramètres étant suffisamment parlant, je ne vais pas revenir dessus en détail et vous propose de voir tout de suite un exemple :

Citation simple :

{% blockquote %}
J'aime les pommes
{% endblockquote %}

Citation utilisant les paramètres :

{% blockquote Ludovic ROLAND, moi http://blog.rolandl.fr mon site %}
J'aime les pommes, il paraît
{% endblockquote %}

Genérez le blog, prévisualisez le et rendez-vous sur l’article ou la page qui contient le code. Vous devriez y découvrir le rendu suivant :

Le plugin Pull Quote

Si par le passé nous avons vu plusieurs plugins pour faire des choses équivalentes, le plugin Pull Quote est véritablement complémentaire au plugin Block Quote. En effet, si le plugin Block Quote nous permet de créer des citations complètes et complexes, le plugin Pull Quote permet quant à lui de mettre en avant une partie d’un paragraphe en le faisant flotter à droite où à gauche du paragraphe complet.

Voyons sa syntaxe :

{% pullquote [left] %}
Ceci est un paragraphe et bientôt nous allons mettre du contenu en avant. Êtes-vous prêts ? Les prochains {" mots seront mis en avant "}. C'est tout !
{% endpullquote %}

Revenons brièvement sur sa syntaxe en commençant par l’unique paramètre left qui est facultatif. S’il n’est pas précisé, la partie du paragraphe mise en avant sera à droite du dit paragraphe alors que s’il est précisé, comme son nom le laisse deviner, la partie du paragraphe mise en avant sera à gauche du paragraphe complet.

Comme vous pouvez le constater, la partie que l’on souhaite mettre en avant dans le paragraphe doit être écrite entre accolades et guillemets, tandis que le paragraphe complet doit être écrit entre les balises du plugin.

Voyons alors un exemple utilisant les deux positionnements possibles :

{% pullquote %}
Ardeo, mihi credite, Patres conscripti (id quod vosmet de me existimatis et facitis ipsi) incredibili quodam amore patriae, qui me amor et subvenire olim impendentibus periculis maximis cum dimicatione capitis, et rursum, cum omnia tela undique esse intenta in patriam viderem, subire coegit atque excipere unum pro universis. {" Hic me meus in rem publicam animus pristinus ac perennis cum C "}. Caesare reducit, reconciliat, restituit in gratiam.
{% endpullquote %}

{% pullquote left %}
Ardeo, mihi credite, Patres conscripti (id quod vosmet de me existimatis et facitis ipsi) incredibili quodam amore patriae, qui me amor et subvenire olim impendentibus periculis maximis cum dimicatione capitis, et rursum, cum omnia tela undique esse intenta in patriam viderem, subire coegit atque excipere unum pro universis. {" Hic me meus in rem publicam animus pristinus ac perennis cum C "}. Caesare reducit, reconciliat, restituit in gratiam.
{% endpullquote %}

Genérez le blog, prévisualisez le et rendez-vous sur l’article ou la page qui contient le code. Vous devriez y découvrir le rendu suivant :