Thanks for this plugin!
Just wanted to offer a suggestion - as a new gulp user, it took me a significant amount of time to figure out how to use it the way I wanted - to parse a markdown file with frontmatter content and perform some transformations on the frontmatter data. Here's an example markdown file:
---
id: introduction
class: step slide
properties: data-x="-1000" data-y="-1500"
---
# Introduction
## Getting Started
Lorem ipsum ...
The documentation gives a clear example of where that data is stored:
property: 'frontMatter', // property added to file object
However - it's only clear now that I've learned about the file objects and pipelines, which was intimidating and time consuming as new user. At first I had absolutely no idea what the file object was or how to access it during the pipeline. It took a lot of learning to understand that one seemingly straight-forward thing.
There are currently several plugins for accessing the data in the pipeline - it seems like gulp-data is intended to be the defacto user-friendly interface, however I couldn't get it to work with gulp-front-matter (probably because I just don't understand it well enough yet).
I eventually found gulp-tap, and used the following code to tap into the pipeline and do what I needed (I put it here, because I've seen this same question asked several times on your issue tracker, on stackoverflow, and in several other places - but was unable to find any published solutions) :
var fs = require('fs');
var gulp = require('gulp');
var gutil = require('gulp-util');
var tap = require('gulp-tap');
var header = require('gulp-header');
var footer = require('gulp-footer');
var concat = require('gulp-concat');
var fm = require('gulp-front-matter');
var marked = require('gulp-markdown');
// Build a single index.html from a glob of markdown files, specifically for use with impressjs.
gulp.task('build:index', function (callback) {
// Parse a glob of markdown files.
gulp.src(src + '/markup/**/*.md')
// Strip the frontmatter - it gets shoved into file.fm['...']
.pipe(fm ({property: 'fm', remove: true}))
// Expose file.fm['..'] variables generated by gulp-front-matter using gulp-tap.
// Because we don't want to write empty tags if the values aren't defined, we
// set default variables that initialize the entire tag attribute.
.pipe(tap(function(file, t) {
slide_id = file.fm['id']==undefined ? '' : 'id="' + file.fm['id'] + '"'
slide_class = file.fm['class']==undefined ? '' : 'class="' + file.fm['class'] + '"'
slide_properties = file.fm['properties']
}))
// Generate html from the remaining markdown.
.pipe(marked())
// Wrap the markup in div tags, generated from the frontmatter.
// If the variables are not defined, an error is not generated, they simply are not
// written. Perfect behavior for my use case, but probably should be more explicit.
.pipe(header('<div <%= slide_id %> <%= slide_class %> <%= slide_properties %>>\n'))
.pipe(footer('</div>\n'))
// Concatenate all the html into a single file.
.pipe(concat('index.html'))
// Wrap the generating html in our impressjs header and footer.
.pipe(header(fs.readFileSync('src/templates/impress-header.tpl', 'utf8')))
.pipe(footer(fs.readFileSync('src/templates/impress-footer.tpl', 'utf8')))
// Write the index file.
.pipe(gulp.dest(dist))
// Fill up our logs.
gutil.log('Recompiled index.html')
});
Hopefully if some other gulp newbie comes along, they'll find this helpful.
Anyway, my suggestion is that it would probably be very helpful to new users if gulp-front-matter was compatible with gulp-data and included an example of how to parse that data, expose it with gulp-data, and then do some example processing.