complex

<%= pkg.description %>

This is an alert

YAML Front Matter

Add YAML front matter to documents to extend the metadata that is supplied to your project's templates.

---
username: jonschlinkert
---

This is probably most useful when: 1. You need to use the same or similar templates on a number of different projects 1. You want to supply data to the templates that won't typically be found in package.json

Code Comments

Code comments may be used in markdown templates, and they will be stripped from the rendered README as long as they adhere to the following syntax:

[[!-- foo --]]
[[! foo ]]
[[!foo]]

Escaping

Escaping hashes

This task automatically adjusts heading levels in included templates. For example, # is adjusted to ##, so that heading levels "line up" properly after the README is built.

This can cause problems if you're using hashes for a reason other than headings, such as CSS Id's in code comments. So to prevent grunt-readme from converting #id {} to ##id {}, just add a single backtick before the hash: `#id {}.

Escaping Lo-Dash templates

To prevent Lo-Dash from attempting to evaluat templates that shouldn't be (as with code examples), just use square brackets instead of curly braces in any templates that have similar patterns to these: [%= .. %], [%- .. %], and [% .. %]. The square brackets will be replaced with curly braces in the rendered output.

foo: bar
version: 2

This is an alert

yfm

A simple to use YAML Front-Matter parsing and extraction Library.

Why another YAML Front Matter library?

Because other libraries we tried failed to meet our requirements with Assemble. Some most of the libraries met most of the requirements, but none had all of them. Here are the most important:

• Be usable, if not simple

• Allow custom delimiters

• Use a dependable and well-supported library for parsing YAML

• Don't fail if YAML front matter exists, but no content

• Don't fail if content exists, but no YAML front matter

• Have no problem reading YAML files directly

• Should return an object that contains the parsed YAML front matter and content, as well as the "original" content.

npm i yfm --save

Usage

var yfm = require('yfm');
yfm('yfm.html');

Options

You may pass an options object as a second parameter.

custom delimiters

Type: object

Default: {close: '---', open: '---'}

Open and close delimiters can be a string or an array of strings. If an array of strings is passed for a delimiter then all patterns supplied will be used to check for YAML front matter.

Example:

{
  close: ['---', '~~~'],
  open: ['...', '---']
}

Checks for all patterns using these delimiters.

Passing multiple delimiters will likely provide unpredictable results, but the option is included for testing purposes.

read

Type: boolean

Default: true

Specify whether or not to read a file from the file system. When set to false a raw string may be passed to the function. Example:

yfm('---\nTitle: YFM\n---\nContent.', {read: false})

Examples

Extract front matter

Let's say our page, foo.html contains

---
title: YAML Front matter
---
<h1>{{title}}</h1>

then running the following in the command line:

console.log(yfm('foo.html'));

returns

{
  "context": {
    "title": "YAML Front matter"
  },
  "content": "<h1>{{title}}</h1>",
  "original": "---\ntitle: YAML Front matter\n---\n<h1>{{title}}</h1>"
}

and

console.log(yfm('foo.html').context);

returns

{"title": "YAML Front matter"}

Check for YAML front matter

var hasYFM = function (src, options) {
  var obj = yfm(src, options).context;
  return _.keys(obj).length > 0;
};

Authors

Jon Schlinkert

• github/jonschlinkert

• twitter/jonschlinkert

Brian Woodward

• github/doowb

• twitter/doowb

License

Copyright (c) 2014 Jon Schlinkert, Brian Woodward, contributors. Released under the MIT license

This file was generated by grunt-readme on Monday, January 27, 2014.