Skip to content
A Node.js module that reads a bunch of markdown files and parses out the yaml front matter
CoffeeScript JavaScript
Latest commit 9efa772 Nov 17, 2014 @rickbergfalk 1.2.1
Failed to load latest commit information.
lib Fix jshint missing semi-colon Nov 7, 2014
test Put context stuff under meta where it belongs Nov 17, 2014
.gitignore
.npmignore Adding to Git! May 25, 2013
CHANGELOG.md version 0.2.0 stuff May 29, 2013
Gruntfile.js
LICENSE.md Adding to Git! May 25, 2013
README.md Add parseFiles and document options Nov 10, 2014
marky-mark.js Put context stuff under meta where it belongs Nov 17, 2014
package.json 1.2.1 Nov 17, 2014

README.md

Marky-mark

Marky-mark helps you consume all your markdown files used for static-site generation.

It reads a directory of files with yaml meta-data/front-matter and parses it out. And if the extension is a markdown one it'll generate the html of that markdown. Add your favorite templating language to make your own static site generator.

Usage

Let's assume you have a folder of markdown files that optionally have front-matter/meta-data, looking something like this:

--- 
title: Marky Mark. A retrospective.
tags:
  - music
  - 90s
whatever: you want
---

## A Blog Post

A blog post about how I can't believe Mark Wahlberg is Marky Mark. 
Written in markdown of course.

You can use marky-mark to easily grab all that data and stick it in an array of javascript objects. All you have to do is:

var mm = require('marky-mark');
var posts = mm.parseDirectorySync(__dirname + "/path/to/posts");

or

var mm = require('marky-mark');
mm.parseDirectory(__dirname + "/path/to/posts", function(err, posts) {

});

Relative paths work too:

var posts = mm.parseDirectorySync('../posts');

The output will be an array of objects, with each object representing 1 file. The front-matter/meta-data is parsed via js-yaml. The parsed result is in the meta property, but the original yaml content is stored in the yaml property in case you want to do something with it.

// this is what .parseDirectorySync() and .parseDirectory() return
[
  {
    filename: "My Marky Mark post.md",
    yaml: "title: Marky Mark. A retrospective.\ntags: ...",
    markdown: "\n## A Blog Post\n\nA blog post about how I ...",
    content: "<h2>A Blog Post</h2><p>A blog post about how I ...",
    meta: {
      title: "Marky Mark. A retrospective.",
      tags: ["music", "90s"],
      whatever: "you want"
    }
  },
  {
    ... another file's contents ...
  }
]

And that's it. It's up to you to do something with all the data marky-mark just read.

API

parseDirectorySync

Parse all markdown files in a given directory, returning a list of context objects.

var mm = require('marky-mark');
var pages = mm.parseDirectorySync('./views/staticPages');

parseMatchesSync

Like parseDirectorySync, parses markdown files in a given directory, but accepts patterns for filtering.

var mm = require('marky-mark');
var pages = mm.parseMatchesSync('./views', ['posts/**/*.md', 'pages/**/*.md', '!**/README.md']);

parseFileSync

Parse a single markdown file.

var mm = require('marky-mark');
var obj = mm.parseFileSync('./views/pages/faq.md');

parseFilesSync

Parse multiple markdown files

var mm = require('marky-mark');
var obj = mm.parseFilesSync(['./views/pages.faq.md', './views/pages/about-me.md']);

parse

Parse a literal markdown string. This is a low-level function used internally by the library, but you might find an independent use for it.

var mm = require('marky-mark');
var obj = mm.parse('# A title\n\n## A subtitle');

parseDirectory

Parse all markdown files in a given directory, returning a list of context objects.

var mm = require('marky-mark');
mm.parseDirectorySync('./views/staticPages', function(err, pages) {

});

parseMatches

Like parseDirectorySync, parses markdown files in a given directory, but accepts patterns for filtering.

var mm = require('marky-mark');
mm.parseMatchesSync('./views', ['posts/**/*.md', 'pages/**/*.md', '!**/README.md'], function(err, pages) {

});

parseFile

Parse a single markdown file.

var mm = require('marky-mark');
mm.parseFileSync('./views/pages/faq.md', function(err, obj) {

});

parseFiles

Parse multiple markdown files

var mm = require('marky-mark');
mm.parseFilesSync(['./views/pages.faq.md', './views/pages/about-me.md'], function(err, objs) {

});

Options

All the above methods accept optional options as the second parameter, where possible options include:

  • preCompile: A function to call with de-ymled markdown. Accepts (and returns) a markdown string.
  • postCompile: A function to call with processed html. Accepts (and returns) an html string.
  • context: An object of additional context properties (extends the front-matter, if any).
  • marked: Options to pass directly to the marked module.

A synchronous usage with options:

var mm = require('marky-mark');
var obj = mm.parseFileSync('./views/pages/faq.md', {
  marked: {
    gfm: true, // Default
    tables: false
  },
  preCompile: function(md) {
    return md.replace('foo', 'bar');
  }
});

An asynchronous usage with options:

var mm = require('marky-mark');
mm.parseFile('./views/pages/faq.md', {
  context: {
    // foo will be added to the "meta" object
    foo: 'bar'
  },
  postCompile: function(html) {
    return html.replace('h1', 'h2');
  }
}, function(err, obj) {

});

Recommended Pairings

Because marky-mark doesn't do anything but read and parse files meant for static-site generators, you'll want to pair it up with other sweet modules to create your own site generator (the funky-bunch approach).

Here are some suggested modules that are fun to use with marky-mark:

If you want to get even crazier, add an http server and a file-watching thing. Then you can generate your site automatically as you write, and see a live preview. Level up your system and automate your deployment.

Notes

Right now marky-mark just parses a directory of markdown files, that optionally have front-matter in yaml. It was a challenge for myself, and something I found useful.

There are lots of ideas for future development in the code, which is relatively simple and small. If anyone wants to add any of these features or add a new one, or improve the code I've already written, feel free.

Pull requests welcome.

Installation

npm install marky-mark

License

MIT

Something went wrong with that request. Please try again.