Format de métadonnées Markdown

il existe deux formats courants qui semblent très semblables, mais qui sont en fait différents de certaines façons très spécifiques. Et un troisième qui est très différent.

YAML Front Matter

le générateur de site statique de Jekyll a popularisé la matière frontale de YAML qui est délimitée par marqueurs de section YAML. Oui, les tirets font en fait partie de la syntaxe YAML. Et les métadonnées sont définies en utilisant n'importe quelle syntaxe YAML valide. Voici un exemple de l' Jekyll docs:

---
layout: post
title: Blogging Like a Hacker
---

notez que YAML front matter n'est pas analysé par L'analyseur Markdown, mais est supprimé avant l'analyse par Jekyll (ou quel que soit l'outil que vous utilisez) et pourrait en fait être utilisé pour demander un analyseur différent de L'analyseur Markdown par défaut pour cette page (je ne me souviens pas si Jekyll fait cela, mais j'ai vu certains outils qui le font).

MultiMarkdown Metadata

le plus vieux et Le plus simple MultiMarkdown Metadata est en fait incorporé dans quelques parsers de Markdown. Bien qu'il ait été récemment mis à jour pour prendre en charge les délimiteurs YAML, traditionnellement, les métadonnées se terminent et le document Markdown Commence sur la première ligne vide (si la première ligne était vide, alors pas de métadonnées). Et bien que la syntaxe ressemble beaucoup à YAML, seules les paires de valeurs clés sont supportées sans types implicites. Voici un exemple de MultiMarkdown docs:

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

Le MultiMarkdown l'analyseur inclut un tas d'options supplémentaires qui sont uniques à cet analyseur, mais les métadonnées de valeur de clé sont utilisées à travers plusieurs analyseurs. Malheureusement, je n'ai jamais vu deux qui se comportent exactement de la même. Sans les règles de Markdown définissant un tel format, chacun a fait sa propre interprétation légèrement différente résultant en beaucoup de variété.

la chose la plus courante est le support des délimiteurs YAML et de la valeur de base de la clé définition.

Pandoc Bloc De Titre

Pour être complet il y a aussi le Pandoc Bloc De Titre. Si a un très syntaxe différente et n'est pas facilement confondu avec les deux autres. À ma connaissance, elle n'est supportée que par Pandoc, et elle ne supporte que trois types de données: le titre, l'auteur et la date. Voici un exemple tiré de la documentation Pandoc:

% title
% author(s) (separated by semicolons)
% date

La plupart des rendus Markdown semblent supporter ce format YAML pour les métadonné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 n'ai pas non plus laissé d'encombrement lorsque je parcourais les fichiers sur Bitbucket où je stocke les fichiers.

Donc j'utilise Abréviations de la syntaxe extra de Markdown.

*[blog-date]: 2018-04-27
*[blog-tags]: foo,bar

puis-je analyser avec regexp:

 ^\*\[blog-date\]:\s*(.+)\s*$

tant que je n'écris pas les mots-clés exacts dans le texte, ils ne laissent aucune trace. Alors utilisez un préfixe obscure assez pour les cacher.

une solution de contournement utilisez la syntaxe standard et compatible avec tous les autres utilisateurs.

je cherchais aussi un moyen d'ajouter des métadonnées spécifiques à l'application dans les fichiers markdown tout en m'assurant que les utilisateurs existants tels que vscode et GitHub page ignoreront les métadonnées ajoutées. Aussi utiliser la syntaxe markdown étendue n'est pas une bonne idée parce que je veux m'assurer que mes fichiers peuvent être rendus correctement sur différents visionneurs.

voici donc ma solution: au début de markdown fichier, utilisez la syntaxe suivante pour ajouter des métadonnées:

  [_metadata_:author]:- "daveying"
  [_metadata_:tags]:- "markdonw metadata"

c'est la syntaxe standard pour les références, et elles ne seront pas rendues tant que votre application pourra extraire ces données.

- après : est juste un placeholder Pour url, Je n'utilise pas url comme valeur parce que vous ne pouvez pas avoir d'espace dans les urls, mais j'ai des scénarios nécessitant des valeurs de tableau.

Je n'ai pas vu cela mentionné ailleurs ici ou 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 markdown pour stocker des métadonnées. Il est un peu plus encombrant à taper par rapport à certains des formats plus textuels ci-dessus, mais il est super facile à analyser. Fondamentalement, je fais juste un regex tel que ^\s*({.*?})\s*(.*)$ (avec s option pour traiter .\n) pour capturer le json et markdown contenu, puis analyser le json avec la méthode standard de la langue. Il permet assez facilement pour arbitraire méta champs.