Marked: support for YAML front matter

[elliottregan]

Like this: http://jekyllrb.com/docs/frontmatter/

[scottgonzalez]

How exactly do you envision this working? The front matter is metadata for a document, which doesn't fit into the return value for a parsed document, which results in just text. This is really a task that needs to be delegated to whatever software is using marked.

[elliottregan]

First, set an option to return an object rather than just text. If a front matter section is present, Marked could return an object like this:

{
meta: {},
content: ""
}

If there is no front matter, it would just return

{
content: ""
}

[scottgonzalez]

This really seems out of scope for marked, but I'll wait for @chjj to respond.

[elliottregan]

I hear that. I just see a few markdown processors supporting meta data, and it's pretty useful to be able to include it.

On Wed, Sep 10, 2014 at 2:29 PM, Scott González [email protected]
wrote:

This really seems out of scope for marked, but I'll wait for @chjj to respond.

Reply to this email directly or view it on GitHub:
https://github.com/chjj/marked/issues/485#issuecomment-55160403

[howardroark]

I certainly agree that the pattern itself is showing to be very useful and quite popular. It makes writing documentation and building sites with Markdown a very sane process. If you plan to use the meta data as an object with your template engine, why not just ready it in one swoop as you parse the document string. Maybe even support HJSON as well?

Though following the UNIX philosophy it would make more sense of there was another project that took the parsed Markdown and went from there. If you think about how Jekyll uses it.... it does allow HTML as well.

[iansinnott]

I just ran into a similar problem where I needed to separate YAML front matter from the markdown content. I ended up using the YAML Front Matter module. Seems to cover this use case pretty well.

[elliottregan]

So, the situ on is to "pre-process" the .md file before sending it to the client? I guess if that is out of the scope of what marked is trying to do, that's fine. I think it would still be great to have support for at least removing meta data.

On Mon, Oct 6, 2014 at 11:48 AM, Ian Sinnott [email protected]
wrote:

I just ran into a similar problem where I needed to separate YAML front matter from the markdown content. I ended up using the [YAML Front Matter module][yml]. Seems to cover this use case pretty well.

[yml]: https://github.com/dworthen/js-yaml-front-matter

Reply to this email directly or view it on GitHub:
https://github.com/chjj/marked/issues/485#issuecomment-58057831

[adam-lynch]

IMO it's out of scope. I've had gulp pipelines like this:

gulp.src('*.md')
    .pipe(gulpFrontMatter()) // stores the front matter object on the File object and removes it from each file contents
    .pipe(gulpMarkdown()) // convert to HTML, metadata is still accessible
    .pipe(gulp.dest('./ouput')) // store HTML
    .pipe(es.map(function(file){
         console.log(file.frontMatter.hello); // stupid example
    });

It should be removed before hand.

[dvcrn]

It's been a year but github is currently parsing front matter into a table. Now that this is part of the official GFM parsing, I think we should put it into marked (into gfm) as well.

e.g.: https://github.com/dvcrn/dvcrn.github.io/blob/master/_posts/2015-10-13-my_dream_editor.markdown

Front matter:

layout: post
title: "My Dream Editor"
date: "2015-10-13 16:05:17 +0900"
---

Output:

[adam-lynch]

@dvcrn if GitHub was, you wouldn't need to use an image as an example right? :stuck_out_tongue_winking_eye:

[elliottregan]

Nice catch! @dvcrn !

@adam-lynch click the other link. You can see it at the top of that page.

[adam-lynch]

Elliott, thanks :). Weird how they render markdown differently here hmm

On Fri, 23 Oct 2015, 17:13 Elliott Regan [email protected] wrote:

Nice catch! @dvcrn https://github.com/dvcrn !

@adam-lynch https://github.com/adam-lynch click the other link. You can
see it at the top of that page.

—
Reply to this email directly or view it on GitHub
https://github.com/chjj/marked/issues/485#issuecomment-150622089.

[elliottregan]

They don't mention it in their docs, but they are definitely showing key-values, even complex ones with arrays, as a table. I still prefer JSON because it's easier to work with, but it makes sense for Github to display it Asa table.

[scottgonzalez]

They don't mention it in their docs

It's probably just left out because it's unrelated to their markdown parser. See https://github.com/blog/1647-viewing-yaml-metadata-in-your-documents

[justinhelmer]

FYI if people are still looking, @adam-lynch's comment here is _conceptually_ the way to go.

In terms of _implementation_, metalsmith is really great for this type of thing, and includes a metalsmith-markdown plugin that is built on top of marked. When used in combination with metalsmith-layouts, you can do some really cool things.

For example (in a gulp pipeline):

function build() {
  var files = ['source/**', '!source/layouts/**', '!source/partials/**'];

  return gulp
      .src(files)
      .pipe(metalsmith({
        use: [
          markdown(),                   // from `metalsmith-markdown` (`marked` wrapper)
          layouts({                     // from `metalsmith-layouts`
            engine: 'handlebars',       // any engine from consolidate.js
            default: 'page.html',
            directory: 'source/layouts',
            partials: 'source/partials',
            pattern: '**/*.html'
          })
        ]
      }))
      .pipe(gulp.dest('build'));
}

metalsmith-layouts is automatically looking for the file.frontMatter property set internally by gulp-front-matter, and using it to render handlebars data for a fixed set of layouts.

Example markdown (myfile.md):

layout:    documentation.html
title:     Documentation - 4.2.1
permalink: /documentation/4.2.1/
---
- some
- list

some content

Example handlebars template used by metalsmith-layouts (documentation.html):

<!DOCTYPE html>
<html>
  <body>
    <h1>{{title}}</h1>
    <main>{{{contents}}}</main>
  </body>
</html>

Outputs (myfile.html):

<!DOCTYPE html>
<html>
  <body>
    <h1>Documentation - 4.2.1</h1>
    <main>
      <ul>
        <li>some</li>
        <li>list</li>
      </ul>
      <p>some content</p>
    </main>
  </body>
</html>

None of this would be possible without the work by @chjj and team, so thanks for that.

I originally came here looking for answers, so hopefully this helps the next guy/gal.

Cheers.

[joshbruce]

See #956

Closing as out of scope for the two targeted specifications of Marked.

[elliottregan]

:( but that makes sense.

[up9cloud]

Memo for browser 😆

<div id="content"></div>
<script src="https://unpkg.com/marked/marked.min.js"></script>
<script src="https://unpkg.com/js-yaml@3/dist/js-yaml.js"></script>
<script src="https://unpkg.com/yaml-front-matter@4/dist/yamlFront.js"></script>
<script>
  let cached_lex = marked.Lexer.lex
  marked.Lexer.lex = function (text, options) {
    let parsed = yamlFront.loadFront(text)
    let cKey = '__content'
    let table = [
      [],
      [],
      []
    ]
    for (let k in parsed) {
      if (k === cKey) {
        continue
      }
      table[0].push(k)
      table[1].push('---')
      table[2].push(parsed[k])
    }
    let tableMd = table.map(row => row.join('|')).join('\n')
    return cached_lex(tableMd + '\n' + parsed[cKey], options)
  }
</script>
<script src="https://unpkg.com/jquery@3/dist/jquery.min.js"></script>
<script>
$(document).ready(function() {
  $.get('https://raw.githubusercontent.com/vuejs/vuejs.org/master/src/v2/examples/index.md', function(str) {
    $("#content").html(marked(str));
  });
});
</script>

[mcapodici]

I want to ignore frontmatter for my scenario.

Here is how I do it:

md = md.replace(/^---$.*^---$/ms, '');

[UziTech]

You can also use front-matter to get any edge cases.

md = frontMatter(md).body;