marky-mark

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.

Up for adoption

If you would like to take ownership of this module or have publishing rights let me know.

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.

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) {
  console.log(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:

• a templating library (EJS, Jade, eco, handlebars, mustache, etc.)
• a date formatting library (such as moment)
• a build tool (grunt)
• a map/reduce or javascript object querying library (I've found taffydb to be super helpful. There's also underscore and lodash.)
• a css preprocessor (like less)

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.

Contributing

Pull requests welcome!

Installation

npm install marky-mark

License

MIT