Ce parseur Markdown-vers-HTML utilise une syntaxe personnalisée et allégée du language Markdown.
Il permet de créer: des textes en italique, textes en gras et textes barrés, des exposants, des liens, des titres et sous-titres, des images, des vidéos, des éléments audios, du code mono et multi lignes, des listes numérotées et non-numérotées, des listes imbriquées, des lignes horizontales, des citations et des notes de bas de page.
Le parseur a été testé avec les versions 10+ de Node.js mais il se peut qu'il fonctionne aussi sur des versions précédentes.
Options du parseur
parse(markdownText[, options])
Un objet avec les options peut être passé au parseur.
Les options disponibles sont:
- allowHeader: Si les titres sont autorisés. true par défaut.
- allowHeaderFormat: Si du texte formaté est aurotisé dans les titres. false par défaut.
- allowLink: Si les liens sont autorisés. true par défaut.
- allowImage: Si les images sont autorisées. true par défaut.
- allowCode: Si du code est autorisé. true par défaut.
- allowMultilineCode: Si du code multi lignes est autorisé. true par défaut.
- allowUnorderedList: Si les listes non-numérotées sont autorisées. true par défaut.
- allowOrderedNestedList: Si les listes numérotées imbriquées sont autorisées. true par défaut.
- allowOrderedList: Si les listes numérotées sont autorisées. true par défaut.
- allowOrderedList: Si les listes numérotées imbriquées sont autorisées. true par défaut.
- allowHorizontalLine: Si les lignes horizontales sont autorisées. true par défaut.
- allowQuote: Si les citations sont autorisées. true par défaut.
- allowFootnote: Si les notes de bas de page sont autorisées. false par défaut.
- allowHTMLAttributes: Si des attributes HTML peuvent sont autorisés. false par défaut (beta).
- maxHeader: Niveau maximal des titres. Nombre de 1 à 6 inclus. e.g. 2 signifie que les balises autorisées sont
et
. 3 par défaut.
Des fonctions Callback peuvent aussi être ajoutées aux options du parseur. Ces fonctions permettent de modifier l'élément de sortie (e.g. ajouter des attributs personnalisés)
Les Callbacks disponibles sont:
- onHeader: Fonction appelée lorsqu'un titre est parsé.
- onLink: Fonction appelée lorsqu'un lien est parsé.
- onImage: Fonction appelée lorsqu'une image est parsée.
- onAudio: Fonction appelée lorsqu'un élément audio est parsé.
- onVidéo: Fonction appelée lorsqu'une video est parsée.
- onCode: Fonction appelée lorsque du code est parsé.
- onMultilineCode: Fonction appelée lorsque du code multi lignes est parsé. Le deuxième argument est le nom (optionnel) du langage.
- onUnorderedList: Fonction appelée lorsqu'une liste non numérotée est parsée.
- onOrderedList: Fonction appelée lorsqu'une liste numérotée est parsée.
- onHorizontalLine: Fonction appelée lorsqu'une ligne horizontale est parsée.
- onQuote: Fonction appelée lorsqu'une citation est parsée.
- onReference: Fonction appelée lorsqu'une référence est parsée. Le deuxième argument contient l'identifiant.
Le premier argument des Callbacks est toujours l'élément parsé.
Le parseur retourne un objet de type Element qui est similaire à un objet DOM Element dans le navigateur.
Les propriétés disponibles sont:
- tagName: Nom de la balise. MDN Docs - id: Attribut id de l'élément. MDN Docs - className: Attribut Class de l'élément. MDN Docs - attributes: Attributs de l'élément. MDN Docs - children: Liste des enfants de type Element. MDN Docs - childNodes: Liste des enfants de type Element et Text. MDN Docs - firstChild: Premier enfant. MDN Docs - lastChild: Dernier enfant. MDN Docs - parentNode: Parent de l'élément. MDN Docs - textContent: Texte de l'élément et de ses descendants. MDN Docs - hasAttribute(attrName): Retourne si l'élément à un attribut spécifique. MDN Docs - setAttribute(attrName, attrValue): Ajoute un attribut à l'élément. MDN Docs - getAttribute(attrName): Retourne un attribute de l'élément. MDN Docs - removeAttribute(attrName): Enlève un attribute de l'élément. MDN Docs - appendChild(child): Ajoute un élément à la fin de la liste des enfants. MDN Docs - prepend(...nodesToPreprend): Insère une liste d'éléments avant le premier enfant. MDN Docs - append(...nodesToAppend): Insère une liste d'éléments après le dernier enfant. MDN Docs - removeChild(child): Enlève un élément. MDN - remove(): Enlève un enfant de son parent. MDN - innerHTML: Retourne la représentation HTML des éléments contenus dans l'élément. MDN Docs - outerHTML: Retourne la représentation HTML de l'élément et de ses descendants. MDN Docs
De nouveaux éléments peuvent être créés en utilisant la classe Element et du texte peut être créé en utilisant la class Text:
`javascript
const { Element, Text } = require('@deskeen/markdown')
const monElementDiv = new Element('div')
const monTexte = new Text('du text')
`
Un texte en italique est entouré d'une étoile (*).
Exemple ` Ceci est un texte en italique `
`html
Ceci est un texte en italique
`
$3
Un texte en gras est entouré de deux étoiles (**).
Exemple ` Ceci est un texte en gras `
`html
Ceci est un texte en gras
`
$3
Un texte en gras-italique est entouré de trois étoiles (*).
Exemple ` Ceci est un texte en gras-italique `
`html
Ceci est un texte en gras-italique
`
$3
Un texte barré est entouré de deux caractères tilde (~~).
Exemple ` Ceci est un ~~texte barré~~
`
`html
Ceci est un texte barré
`
$3
Un texte en exposant commence par un caractère circonflexe (^) et termine avec un espace ou un saut de ligne. Un texte en exposant qui contient des espaces peut être entouré de parenthèses.
Exemple ` Ceci est un ^texte en exposant
`
`html
Ceci est un texte en exposant
`
Exemple avec parenthèses ` Ceci est un ^(texte en exposant)
`
`html
Ceci est un texte en exposant
`
Paragraphe
Un seul saut de ligne ajoute le text au dernier paragraphe. Deux sauts de ligne à la suite créé un nouveau paragraphe.
Exemple avec un seul saut de ligne ` Première ligne de texte
Seconde ligne de texte
`
`html
Première ligne de texte Seconde ligne de texte
`
Example with two newlines ` Première ligne de texte
Seconde ligne de texte
`
`html
Première ligne de texte
Seconde ligne de texte
`
$3
Un titre commence par un à six caractères dièse (#), suivi d'un espace.
Exemple `
Titre niveau 1
Titre niveau 2
$3
#### Titre niveau 4
##### Titre niveau 5
###### Titre niveau 6
`
`html
Titre niveau 1
Titre niveau 2
Titre niveau 3
Titre niveau 4
Titre niveau 5
Titre niveau 6
`
$3
Un lien est composé de deux parties. Le texte, entouré de crochets ([]) suivi du lien, entouré de parenthèses (( )), i.e. Link. Les crochets fermants dans le texte doivent être précédés du caractère d'échappement.
Une image commence par un point d'exclamation (!) suivie d'un texte alternatif entouré de de crochets ([]), suivi de l'adresse (URL) entouré de parenthèses (( )). i.e. !text alt.
Les images mises sur une ligne séparée et les images contenues dans une ligne de texte génèrent un code HTML différent.
Exemple d'une image sur une ligne de texte ` Cette !image fait partie d'une ligne de texte
`
Exemple d'une image avec du CSS ` !Image avec style{style="height: 100px; width: 100px"}
`
`html
`
Vidéo
Les vidéos fonctionnent de la même manière que les images, i.e. ![][adresse_de_la_video].
Exemple d'une vidéo
` ![][https://exemple.com/une_video.mp4]
`
`html
`
Exemple d'une vidéo avec légende
` ![][https://exemple.com/une_video.mp4 "ma légende"]
`
`html
ma légende
`
Audio
Les éléments audios fonctionnent de la même manière que les images, i.e. ![][adresse_du_son].
Exemple d'un son ` ![][https://example.com/some_audio.mp3]
`
`html
`
Exemple d'un son avec légende ` ![][https://example.com/some_audio.mp3 "ma légende"]
`
`html
ma légende
`
Liste non numérotée
Les éléments d'une liste non numérotée commencent avec un tiret (-) suivi par un espace.
Des sauts de lignes peuvent être insérées à l'intérieur d'un élément de la liste en commençant la ligne avec deux espaces.
Une liste peut être imbriquée dans une autre liste en commençant avec au moins deux espaces, suivi d'un tiret, et d'un autre espace. Seulement une liste de même type peut être imbriquée.
Exemple ` - Item 1
- Item 2
- Item 3
`
`html
Item 1
Item 2
Item 3
`
Exemple avec un saut de ligne à l'intérieur d'un élément ` 1. Item 1
Suite Item 1
2. Item 2
`
`html
Item 1 Suite Item 1
Item 2
`
Exemple avec une liste imbriquée ` - Item 1
- Item 1.1
- Item 1.2
- Item 2
`
`html
Item 1
Item 1.1
Item 1.2
Item 2
`
Liste numérotée
Les éléments d'une liste numérotée commencent avec un nombre suivi par un point (.) et un espace.
Des sauts de lignes peuvent être insérées à l'intérieur d'un élément de la liste en commençant la ligne avec trois espaces.
Une liste peut être imbriquée dans une autre liste en commençant avec au moins trois espaces, suivi d'un nombre, et d'un espace. Seulement une liste de même type peut être imbriquée.
Exemple ` 1. Item 1
2. Item 2
3. Item 3
`
`html
Item 1
Item 2
Item 3
`
Exemple avec un saut de ligne à l'intérieur d'un élément ` 1. Item 1
Suite Item 1
2. Item 2
`
`html
Item 1 Suite Item 1
Item 2
`
Les nombres des éléments des listes numérotées ne sont pas pris en compte. La liste est exportée de la même façon si les nombres se suivent ou pas.
Exemple avec des nombres qui ne se suivent pas ` 5. Item 1
1. Item 2
8. Item 3
3. Item 4
`
`html
Item 1
Item 2
Item 3
Item 4
`
Exemple avec une liste imbriquée ` 1. Item 1
1. Item 1.1
2. Item 1.2
2. Item 2
`
`html
Item 1
Item 1.1
Item 1.2
Item 2
`
Ligne horizontale
Une ligne horizontale débute avec une ligne vide, suivi de trois tirets (---), suivi d'une autre ligne vide.
Exemple ` Au dessus de la ligne horizontale
---
En dessous de la ligne horizontale
`
`html
Au dessus de la ligne horizontale
En dessous de la ligne horizontale
`
Code
Le code est entouré du accent aigu (\`).
Exemple ` Ceci est du code technique `
`html
Ceci est du code technique
`
Code multi lignes
Du code multi lignes est entouré par trois accents aigus (\`), mis sur des lignes séparées.
Le langage du code peut être ajouté à côté des trois accents aigus d'ouverture. Il n'est pas affiché dans le code HTML de sorti mais il est passé en deuxième argument du Callback onMultilineCode. Voir l'exemple plus bas.
Exemple ` \\\ Du code ligne 1
Du code ligne 2
Du code ligne 3
\\\ `
`html
Du code ligne 1
Du code ligne 2
Du code ligne 3
`
Exemple avec un nom de language ` \\\javascript
console.log('Hello World!')
\\\ `
`html
console.log('Hello World!')
`
Citation
Une citation débute avec un signe supérieur (>).
Exemple ` > Citation ligne 1
> Citation ligne 2
> Citation ligne 3
`
`html
Citation ligne 1
Citation ligne 2
Citation ligne 3
`
Note de bas de page
Une note de bas de page est composée de deux parties: une référence et une note.
La référence commence avec un crochet ouvrant ([), suivi d'un accent circonflexe (^), un identifiant (un nombre ou un texte mais pas d'espaces), et un crochet fermant (]). e.g. [^1]
La note doit être sur sa propre ligne n'importe où dans le document et doit correspondre avec la référence. Un double point (:) est ajouté à côté de la référence suivi du texte de la note.
L'identifiant de la référence est seulement utilisé pour faire le lien entre la référence et la note de bas de page. Le code HTML de sortie sera numéroté de façon séquentielle.
Exemple ` Ma première référence[^1].
Ma seconde[^two].
[^1]: 1ere note de bas de page.
[^two]: 2eme note de bas de page.
`
- Les textes en italiques et en gras avec un, deux et trois underscores.
- Les titres avec des tirets ou des signes égal en dessous.
- Les listes non-numérotées avec un signe plus ou une étoile.
- Plus d'une liste imbriquée.
- Les lignes horizontales avec des étoiles ou des underscores.
- Les liens entre inférieur et supérieur.
- Le code HTML.
Exemples
$3
`javascript
parseMarkdown('# Title 1', {
onHeader: element => {
// node.textContent === 'Title 1'
Vous pouvez:
- Jeter un coup d'oeil aux problèmes et voir si vous pouvez aider quelqu'un.
- Jeter un coup d'oeil au code et voir si vous pouvez l'améliorer.
- Traduire cette page dans votre langue.
- Mettre une étoile à ce dépôt.
Contact
Vous pouvez me contacter à l'adresse {mon_prenom}@{mon_nom}.fr
fait partie d'une ligne de texte
