Markdown metadata format

pandoc template
markdown table
pandoc multiple files
markdown javascript
pandoc title page
markdown front matter
markdown cheat sheet
yaml metadata block

Is there a standard or convention for embedding metadata in a Markdown formatted post, such as the publication date or post author for conditional rendering by the renderer?

Looks like this Yaml metadata format might be it.

There are all kinds of strategies, e.g. an accompanying file mypost.meta.edn, but I'm hoping to keep it all in one file.

There are two common formats that look very similar but are actually different in some very specific ways. And a third which is very different.

YAML Front Matter

The Jekyll static site generator popularized YAML front matter which is deliminated by YAML section markers. Yes, the dashes are actually part of the YAML syntax. And the metadata is defined using any valid YAML syntax. Here is an example from the Jekyll docs:

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

Note that YAML front matter is not parsed by the Markdown parser, but is removed prior to parsing by Jekyll (or whatever tool you're using) and could actually be used to request a different parser than the default Markdown parser for that page (I don't recall if Jekyll does that, but I have seen some tools which do).

MultiMarkdown Metadata

The older and simpler MultiMarkdown Metadata is actually incorporated into a few Markdown parsers. While it has more recently been updated to optionally support YAML deliminators, traditionally, the metadata ends and the Markdown document begins upon the first blank line (if the first line was blank, then no metadata). And while the syntax looks very similar to YAML, only key-value pairs are supported with no implied types. Here is an example from the 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

The MultiMarkdown parser includes a bunch of additional options which are unique to that parser, but the key-value metadata is used across multiple parsers. Unfortunately, I have never seen any two which behaved exactly the same. Without the Markdown rules defining such a format everyone has done their own slightly different interpretation resulting in a lot of variety.

The one thing that is more common is the support for YAML deliminators and basic key-value definitions.

Pandoc Title Block

For completeness there is also the Pandoc Title Block. If has a very different syntax and is not easily confused with the other two. To my knowledge, it is only supported by Pandoc (if enabled), and it only supports three types of data: title, author, and date. Here is an example from the Pandoc documentation:

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

Note that Pandoc Title Blocks are one of two style supported by Pandoc. Pandoc also supports YAML Metadata as described above. Neither extension is enabled by default.

Markdown Metadata, Simply add the metadata to the top of a markdown file as follows: Yet if I format this document for HTML or PDF using Marked, the metadata  Simply add the metadata to the top of a markdown file as follows: The metadata is just a set of key-value pairs, where the key is before the : and the value after. The keys can be anything you want them to be, although Fletcher Penney, creator of MultiMarkdown, has recommended some standard ones here.

Most Markdown renderers seem to support this YAML format for metadata at the top of the file:

---
layout: post
published-on: 1 January 2000
title: Blogging Like a Boss
---

Content goes here.

Markdown & metadata, For example, a pattern with the title “Menu button” should probably have the Like many static site generators, Hugo lets you add metadata to its markdown files  The object metadata stores the YAML metadata of the current R Markdown document as a list, Format. An object of class

A workaround use standard syntax and compatible with all other viewers.

I was also looking for a way to add application specific metadata to markdown files while make sure the existing viewers such as vscode and github page will ignore added metadata. Also to use extended markdown syntax is not a good idea because I want to make sure my files can be renderred correctly on different viewers.

So here is my solution: at beginning of markdown file, use following syntax to add metadata:


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

This is the standard syntax for references, and they will not be renderred while your application can extract these data out.

The - after : is just a placeholder for url, I don't use url as value because you cannot have space in urls, but I have scenarios require array values.

MultiMarkdown Syntax Guide · fletcher/MultiMarkdown Wiki · GitHub, This is a guide to the markup syntax used in the MultiMarkdown system To use metadata, simply add information to the top of a Markdown file  And if you wish to export more metadata from the notebook, have a look at the paragraph on metadata filtering. In the Markdown format, markdown cells are inserted verbatim and separated with two blank lines.

This is not a standard way, but works with Markdown Extra.

I wanted something that worked in the parser, but also didn't leave any clutter when I browse the files on Bitbucket where I store the files.

So I use Abbreviations from the Markdown Extra syntax.

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

then I parse them with regexp:

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

As long as I don't write the exact keywords in the text, they leave no trace. So use some prefix obscure enough to hide them.

Pandoc's Markdown, Pandoc's enhanced version of Markdown includes syntax for tables, definition lists, metadata blocks, footnotes, citations, math,  In this way, if you pass your document through a regular version of Markdown, the metadata will be properly formatted as plain text with line breaks, rather than joined into a single run-on paragraph.

I haven't seen this mentioned elsewhere here or in various blogs discussing the subject, but in a project for my personal website, I've decided to use a simple JSON object at the top of each markdown file to store metadata. It's a little more cumbersome to type compared to some of the more textual formats above, but it's super easy to parse. Basically I just do a regex such as ^\s*({.*?})\s*(.*)$ (with the s option on to treat . as \n) to capture the json and markdown content, then parse the json with the language's standard method. It allows pretty easily for arbitrary meta fields.

Standardized metadata layer?, My 'metadata layer' project, in short: If markdown is a standard way of of it, markdown just provides a way of formatting the text of the 'content'  Nearly all Markdown applications support the basic syntax outlined in John Gruber’s original design document. There are minor variations and discrepancies between Markdown processors — those are noted inline wherever possible. Headings. To create a heading, add number signs (#) in front of a word or phrase. The number of number signs you use should correspond to the heading level.

Markdown Syntax Documentation, Markdown's syntax is intended for one purpose: to be used as a format for By allowing you to move the markup-related metadata out of the paragraph, you can​  Markdown is a way to style text on the web. You control the display of the document; formatting words as bold or italic, adding images, and creating lists are just a few of the things we can do with Markdown. Mostly, Markdown is just regular text with a few non-alphabetic characters thrown in, like # or *.

Metadata for markdown / MkDocs, Markdown is a widely used simple text format that allows formatting of text using inline markup, it's a bit like the markup used on mediawiki/  Tables. Tables aren't part of the core Markdown spec, but they are part of GFM and Markdown Here supports them. They are an easy way of adding tables to your email -- a task that would otherwise require copy-pasting from another application. Colons can be used to align columns. | Tables | Are | Cool | | -------------

Metadata in Scholarly Markdown, For Scholarly Markdown we have another requirement: the metadata should be writeable and readable by humans. YAML is the perfect format  Pandoc is a Haskell library for converting from one markup format to another, and a command-line tool that uses this library. Pandoc can convert between numerous markup and word processing formats, including, but not limited to, various flavors of Markdown, HTML, LaTeX and Word docx.

Comments
  • What’s up with the self-question link in Pandoc title block? Also, the %title etc example does not work for me.
  • @isomorphismes thanks for pointing out the broken link, Now fixed. Also, I added a few clarifications. You need to explicitly enable the Pandoc extension for it to work.
  • An additional note: Hexo supports JSON front matter as well as YAML.