Format des métadonnées de Markdown
Existe-t-il une norme ou une convention pour l’incorporation de métadonnées dans une publication au format Markdown, telle que la date de publication ou l’auteur de publication pour le rendu conditionnel par le rendu?
On dirait que/ métadonnées Yaml format pourrait être ça.
Il existe toutes sortes de stratégies, par exemple un fichier d’accompagnement mypost.meta.edn, mais j’espère garder tout cela dans un seul fichier.
Il existe deux formats courants qui se ressemblent beaucoup mais qui sont en réalité très différents. Et un troisième qui est très différent.
YAML Front Matter
Le générateur de site statique de Jekyll a popularisé l’avant-train YAML qui est éliminé par les marqueurs de section YAML . Oui, les tirets font en réalité partie de la syntaxe YAML. Et les métadonnées sont définies en utilisant une syntaxe YAML valide. Voici un exemple tiré de Jekyll docs :
--- layout: post title: Blogging Like a Hacker ---
Notez que le préambule YAML n’est pas analysé par l’analyseur Markdown, mais est supprimé avant l’analyse par Jekyll (ou l’outil que vous utilisez) et peut en fait être utilisé pour demander un analyseur différent de celui de l’analyseur Markdown par défaut pour cette page (I Je ne me souviens pas si Jekyll le fait, mais j’ai vu des outils le faire).
Métadonnées MultiMarkdown
L'ancien et plus simple MultiMarkdown Metadata est en fait incorporé dans quelques analyseurs syntaxiques de Markdown. Bien qu’il ait été mis à jour plus récemment pour prendre éventuellement en charge les suppresseurs YAML, les métadonnées se terminent généralement et le document Markdown commence à la première ligne vierge (si la première ligne était vide, aucune métadonnée). Et bien que la syntaxe ressemble beaucoup à YAML, seules les paires clé-valeur sont prises en charge sans types implicites. Voici un exemple tiré de la documentation MultiMarkdown:
Title: A Sample MultiMarkdown Document Author: Fletcher T. Penney Date: February 9, 2011 Comment: This is a comment intended to demonstrate metadata that spans multiple lines, yet is treated as a single value. CSS: http://example.com/standard.css
L'analyseur MultiMarkdown inclut un ensemble d'options supplémentaires qui sont uniques à cet analyseur, mais les métadonnées clé-valeur sont utilisées sur plusieurs analyseurs. Malheureusement, je n'ai jamais vu deux personnes se comportant exactement de la même manière. Sans les règles de Markdown définissant un tel format, tout le monde a fait sa propre interprétation légèrement différente, ce qui a créé beaucoup de variété.
La chose la plus commune est le support des déliminateurs YAML et des définitions de base clé-valeur.
Cartouche Pandoc
Pour être complet, il existe également le bloc de titre Pandoc . Si a une syntaxe très différente et ne se confond pas facilement avec les deux autres. À ma connaissance, il n’est pris en charge que par Pandoc (s’il est activé) et ne prend en charge que trois types de données: titre, auteur et date. Voici un exemple tiré de la documentation Pandoc:
% title
% author(s) (separated by semicolons)
% date
Notez que les cartouches Pandoc sont l’un des deux styles pris en charge par Pandoc. Pandoc prend également en charge - Métadonnées YAML comme décrit ci-dessus. Aucune des deux extensions n'est activée par défaut.
La plupart des moteurs de rendu Markdown semblent prendre en charge ce format YAML pour les métadonnées situées en haut du fichier:
---
layout: post
published-on: 1 January 2000
title: Blogging Like a Boss
---
Content goes here.
Ce n'est pas une méthode standard, mais fonctionne avec Markdown Extra.
Je voulais quelque chose qui fonctionnait dans l'analyseur, mais je ne laissais pas non plus de fouillis lorsque je parcourais les fichiers sur Bitbucket où je stockais les fichiers.
J'utilise donc Abréviations de la syntaxe Markdown Extra.
*[blog-date]: 2018-04-27
*[blog-tags]: foo,bar
alors je les analyse avec l'expression rationnelle:
^\*\[blog-date\]:\s*(.+)\s*$
Tant que je n'écris pas les mots-clés exacts dans le texte, ils ne laissent aucune trace. Utilisez donc un préfixe assez obscur pour les cacher.
Je n'ai pas vu cela mentionné ailleurs ni dans divers blogs traitant du sujet, mais dans un projet pour mon site Web personnel, j'ai décidé d'utiliser un simple objet JSON en haut de chaque fichier de démarquage pour stocker des métadonnées. Il est un peu plus lourd de taper par rapport à certains des formats plus textuels ci-dessus, mais il est très facile à analyser. Fondamentalement, je fais juste une expression rationnelle telle que ^\s*({.*?})\s*(.*)$ (avec l'option s pour traiter . en tant que \n) pour capturer le contenu json et markdown, puis analyser le json avec la méthode standard du langage. Cela permet assez facilement pour les méta-champs arbitraires.
Une solution de contournement utilise une syntaxe standard et compatible avec tous les autres visualiseurs.
Je recherchais également un moyen d’ajouter des métadonnées spécifiques à l’application aux fichiers de démarques tout en veillant à ce que les lecteurs existants, tels que vscode et la page github, ignorent les métadonnées ajoutées. Aussi, utiliser la syntaxe de démarquage étendu n'est pas une bonne idée car je veux m'assurer que mes fichiers peuvent être restitués correctement sur différents visualiseurs.
Voici donc ma solution: au début du fichier de démarquage, utilisez la syntaxe suivante pour ajouter des métadonnées:
[_metadata_: auteur]: - "daveying" [_metadata_: tags]: - "markdonw metadata"
Il s'agit de la syntaxe standard pour les références et elles ne seront pas restituées tant que votre application pourra extraire ces données.
Le - après le : est simplement un espace réservé pour l'URL. Je n'utilise pas l'URL comme valeur car vous ne pouvez pas laisser d'espace dans les URL, mais j'ai des scénarios qui nécessitent des valeurs de tableau.