Formats de Contenus Supportés

Markdown est le principal format de contenu et il est livré avec deux saveurs : l’excellent projet Blackfriday(nommez vos fichiers *.md ou réglez markup = "markdown" dans le front matter) ou son fork Mmark (nommez vos fichiers *.mmark ou réglez markup = "mmark" dans le front matter), tous les deux étant deux moteurs rapides markdown écrits en Go.

Pour les utilisateurs d’Emacs, goorgeous fournit un support natif intégré pour Org-mode (nommez vos fichiers *.org ou définissez markup = "org" dans le front matter).

Configurer un Rendu Markdown BlackFriday

Vous pouvez configurer plusieurs aspects de Blackfriday comme indiqué dans la liste suivante. Voir la documentation sur Configuration pour la liste complète des instructions explicites que vous pouvez donner à Hugo lors du rendu de votre site.

taskLists: default: true
Blackfriday flag:
Purpose: false turns off GitHub-style automatic task/TODO list generation
smartypants: default: true
Blackfriday flag: HTML_USE_SMARTYPANTS
Purpose: false disables smart punctuation substitutions, including smart quotes, smart dashes, smart fractions, etc. If true, it may be fine-tuned with the angledQuotes, fractions, smartDashes, and latexDashes flags (see below).
angledQuotes: default: false
Blackfriday flag: HTML_SMARTYPANTS_ANGLED_QUOTES
Purpose: true enables smart, angled double quotes. Example: “Hugo” renders to renders to «Hugo» instead of “Hugo”.
fractions: default: true
Blackfriday flag: HTML_SMARTYPANTS_FRACTIONS
Purpose: false disables smart fractions.
Example: 5/12 renders to ⁵⁄₁₂(<sup>5</sup>&frasl;<sub>12</sub>).
Caveat: Even with fractions = false, Blackfriday still converts 1/2, 1/4, and 3/4 respectively to ½ (½), ¼ (¼) and ¾ (¾), but only these three.
smartDashes: default: true
Blackfriday flag: HTML_SMARTY_DASHES
Purpose: false disables smart dashes; i.e., the conversion of multiple hyphens into an en dash or em dash. If true, its behavior can be modified with the latexDashes flag below.
latexDashes: default: true
Blackfriday flag: HTML_SMARTYPANTS_LATEX_DASHES
Purpose: false disables LaTeX-style smart dashes and selects conventional smart dashes. Assuming smartDashes:
If true, -- is translated into – (–), whereas --- is translated into — (—).
However, spaced single hyphen between two words is translated into an en dash— e.g., “12 June - 3 July” becomes 12 June ndash; 3 July upon rendering.
hrefTargetBlank: default: false
Blackfriday flag: HTML_HREF_TARGET_BLANK
Purpose: true opens external links in a new window or tab.
plainIDAnchors: default true
Blackfriday flag: FootnoteAnchorPrefix and HeaderIDSuffix
Purpose: true renders any heading and footnote IDs without the document ID.
Example: renders #my-heading instead of #my-heading:bec3ed8ba720b970
extensions: default: []
Blackfriday flag: EXTENSION_*
Purpose: Enable one or more Blackfriday’s Markdown extensions (if they aren’t Hugo defaults).
Example: Include hardLineBreak in the list to enable Blackfriday’s EXTENSION_HARD_LINK_BREAK
extensionsmask: default: []
Blackfriday flag: EXTENSION_*
Purpose: Enable one or more of Blackfriday’s Markdown extensions (if they aren’t Hugo defaults).
Example: Include autoHeaderIds as false in the list to disable Blackfriday’s EXTENSION_AUTO_HEADER_IDS.

Étendre le Markdown

Hugo fournit des méthodes pratiques pour étendre le markdown.

Listes de tâches

Hugo prend en charge les listes de tâches de style GitHub (c.-à-d. Listes TODO) pour le rendu markdown Blackfriday. Si vous ne souhaitez pas utiliser cette fonctionnalité, vous pouvez la désactiver dans votre configuration.

Exemple Input de Liste de Tâches

content/my-to-do-list.md

- [ ] un item de liste de tâche
- [ ] syntaxe de liste exigée
- [ ] incomplète
- [x] complète

Exemple Output de Liste de Tâches

Le markdown précédent produit le HTML suivant dans votre site web produit :

<ul class="task-list">
    <li><input type="checkbox" disabled="" class="task-list-item"> a task list item</li>
    <li><input type="checkbox" disabled="" class="task-list-item"> list syntax required</li>
    <li><input type="checkbox" disabled="" class="task-list-item"> incomplete</li>
    <li><input type="checkbox" checked="" disabled="" class="task-list-item"> completed</li>
</ul>

Exemple d’Affichage d’une Liste de Tâches

Ce qui suis présente comment l’exemple de liste de tâches s’affichera pour les utilisateurs finaux de votre site web. Notez que l’apparence visuelle des listes ne dépend que de vous. Cette liste a été stylisée selon la feuille de style Hugo Docs.

un item de liste de tâche
syntaxe de liste exigée
incomplet
achevé

Emojis

Pour ajouter des emojis directement au contenu, réglez enableEmoji sur true dans votre configuration de site. Pour utiliser les emojis dans des modèles ou des codes courts, voir la fonction emojify.

Pour une liste complète d’emojis, consultez l’anti-sèche Emoji.

Shortcodes

Si vous écrivez en Markdown et que vous vous trouverez souvent en train d’intégrer votre contenu avec du HTML brut, Hugo fournit des fonctionnalités inégrées de raccourcis-code. C’est l’une des fonctionnalités les plus puissantes d’Hugo et elle vous permet de créer rapidement vos propres extensions Markdown.

Voir Shortcodes pour l’utilisation, en particulier pour les codes courts intégrés qui sont livrés avec Hugo, et Modélisation code court pour apprendre à construire les vôtres.

Blocs de Code

Hugo supporte l’usage du markdown enrichi de GitHub des trois tiques inversées tout comme un raccourci-code imbriqué highlight pour rendre une syntaxe colorée via via Pygments. Pour des exemples d’usage et une explication complète, regardez la documentation éclairage de syntaxe dans les outils du développeur.

Mmark

Mmark est une bifurcation de BlackFriday et un super-ensemble de markdown qui convient parfaitement à l’écriture pour la documentation IETF. Vous pouvez voir des exemples de la syntaxe dans le référentiel Mmark GitHub ou la syntaxe complète sur le site Web de Miek Gieben.

Utiliser Mmark

Comme Hugo est livré avec Mmark, l’utilisation de la syntaxe est aussi simple que de changer l’extension de vos fichiers de contenu de .md à .mmark.

Dans le cas où vous souhaitez utiliser uniquement Mmark dans des fichiers spécifiques, vous pouvez également définir la syntaxe Mmark dans le front matter de votre contenu :

---
title: Mon Super Post
date: 2017-07-18
markdown: mmark
---

MathJax avec Hugo

MathJax is a JavaScript library that allows the display of mathematical expressions described via a LaTeX-style syntax in the HTML (or Markdown) source of a web page. As it is a pure a JavaScript library, getting it to work within Hugo is fairly straightforward, but does have some oddities that will be discussed here.

This is not an introduction into actually using MathJax to render typeset mathematics on your website. Instead, this page is a collection of tips and hints for one way to get MathJax working on a website built with Hugo.

MathJax est une bibliothèque JavaScript qui permet d’afficher des expressions mathématiques décrites par une syntaxe de type LaTeX dans la source HTML (ou Markdown) d’une page Web. Comme il s’agit d’une pure bibliothèque JavaScript, le faire fonctionner dans Hugo est assez simple, mais il y a des bizarreries qui seront discutées ici.

Ce n’est pas une introduction à l’utilisation de MathJax pour afficher les caractères mathématiques sur votre site. Au lieu de cela, cette page est une collection de conseils et d’astuces pour une façon de faire fonctionner MathJax sur un site Web construit avec Hugo.

Activer MathJax

La première étape consiste à activer MathJax sur les pages où vous souhaitez avoir des caractères mathématiques. Il y a plusieurs façons de le faire (les lecteurs aventureux peuvent consulter la section Chargement et Configuration de la documentation MathJax pour des méthodes supplémentaires d’inclusion de MathJax). Mais la façon la plus simple est d’utiliser le CDN sécurisé MathJax en incluant une balise <script> pour le CDN sécurisé officiellement recommandé (cdn.js.com) :

add-mathjax-to-page.html

<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>

Une façon de s’assurer que ce code est inclus dans toutes les pages est de le placer dans l’un des modèles dans le répertoire layouts/partials/. Par exemple, je l’ai inclus dans le bas de mon modèle footer.html car je sais que le pied de page sera inclus dans chaque page de mon site.

Options et Fonctionnalités

MathJax est une bibliothèque stable open-source avec de nombreuses fonctionnalités. J’encourage le lecteur intéressé à regarder la Documentation MathJax, en particulier les sections sur l’Utilisation de Base et les Options de Configuration MathJax.

Problèmes avec Markdown

Après avoir activé MathJax, toutes les entrées mathématiques entre les marqueurs appropriés (voir la documentation MathJax) seront traitées et restranscrites dans la page Web. Un problème se pose cependant avec Markdown : le caractère de soulignement (_) est interprété par Markdown comme un moyen d’envelopper du texte dans des blocs emph tandis que LaTeX (MathJax) interprète le trait de soulignement comme un moyen de créer un sous-titre . Ce «double parler» du trait de soulignement peut entraîner des comportements inattendus et indésirables.

Solution

Il existe plusieurs façons de remédier à ce problème. Une solution consiste à échapper à chaque trait de soulignement dans votre code mathématique en entrant \_ au lieu de _. Cela peut devenir très fastidieux si les équations que vous entrez sont pleines d’indices.

Une autre option est de dire à Markdown de traiter le code MathJax comme un code textuel et de ne pas le traiter. Une façon de le faire est d’envelopper l’expression mathématique dans un bloc <div> </div>. Markdown ignorera ces sections et elles seront transmises directement à MathJax et traitées correctement. Cela fonctionne bien pour les mathématiques de style d’affichage, mais pour les expressions mathématiques en ligne, la rupture de ligne induite par <div> n’est pas acceptable. La syntaxe pour instruire Markdown pour traiter le texte en ligne comme textuel est en l’enveloppant dans les backticks ( `). Vous avez peut-être remarqué, cependant, que le texte inclus entre les backticks est restitué différemment du texte standard (sur ce site, il s’agit d’éléments mis en surbrillance en rouge). Pour contourner ce problème, nous pourrions créer une nouvelle entrée CSS qui applique un style standard pour tout texte en ligne verbatim qui inclut le code MathJax. Ci-dessous je vais montrer la source HTML et CSS qui accomplirait cette (note cette solution a été adaptée de ce blog - Tous les crédits reviennent à l’auteur original).

mathjax-markdown-solution.html

<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  tex2jax: {
    inlineMath: [['$','$'], ['\\(','\\)']],
    displayMath: [['$$','$$'], ['\[','\]']],
    processEscapes: true,
    processEnvironments: true,
    skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
    TeX: { equationNumbers: { autoNumber: "AMS" },
         extensions: ["AMSmath.js", "AMSsymbols.js"] }
  }
});
</script>

<script type="text/x-mathjax-config">
  MathJax.Hub.Queue(function() {
    // Fix <code> tags after MathJax finishes running. This is a
    // hack to overcome a shortcoming of Markdown. Discussion at
    // https://github.com/mojombo/jekyll/issues/199
    var all = MathJax.Hub.getAllJax(), i;
    for(i = 0; i < all.length; i += 1) {
        all[i].SourceElement().parentNode.className += ' has-jax';
    }
});
</script>

Comme précédemment, ce contenu devrait être inclus dans la source HTML de chaque page qui utilisera MathJax. L’extrait de code suivant contient le CSS qui est utilisé pour que les blocs MathJax textuels contiennent le même style de police que le corps de la page.

mathjax-style.css

code.has-jax {
    font: inherit;
    font-size: 100%;
    background: inherit;
    border: inherit;
    color: #515151;
}

Dans l’extrait CSS, notez la ligne color: #515151;. #515151 est la valeur attribuée à l’attribut color de la classe body dans ma CSS. Pour que les équations s’inscrivent dans le corps d’une page Web, cette valeur devrait être identique à la couleur du corps.

Usage

Avec cette configuration, tout est en place pour une utilisation naturelle de MathJax sur les pages générées à l’aide d’Hugo. Pour inclure les mathématiques en ligne, il suffit de mettre le code LaTeX entre `$ TeX Code $` ou `$ TeX Code $`. Pour inclure le style mathématiques, placez juste le code LaTeX entre <div>$$TeX Code$$</div>. Tous les maths seront correctement composés et affichés dans votre page web générée par Hugo !

Formats Supplémentaires via les Aides Externes

Hugo a un nouveau concept appelé «aide extérieure». Cela signifie que vous pouvez écrire votre contenu en utilisant Asciidoc, reStructuredText. Si vous avez des fichiers avec des extensions associées, Hugo appellera des commandes externes pour générer le contenu. (Voir le code source Hugo pour les assistants externes.)

Par exemple, pour les fichiers Asciidoc, Hugo essaiera d’appeler la commande asciidoctor ou asciidoc. Cela signifie que vous devrez installer l’outil associé sur votre machine pour pouvoir utiliser ces formats. (Voir les documents Asciidoctor pour les instructions d’installation).

Pour utiliser ces formats, utilisez simplement l’extension standard et le front matter exactement comme vous le feriez avec les fichiers .md supportés nativement.

Apprendre le Markdown

La syntaxe Markdown est suffisamment simple à apprendre en une seule séance. Les ressources qui suivent sont excellentes pour vous mettre en route :