metalsmith-matters - npm Package Compare versions

Comparing version 1.0.0 to 1.1.0

lib/index.js

 var matter = require('gray-matter');
 var utf8 = require('is-utf8');
+var each = require('metalsmith-each');
 
@@ -28,8 +29,10 @@ module.exports = frontmatter;
 
-function extractFrontmatter(file, filePath){
+function extractFrontmatter(file, filePath, options){
   if (utf8(file.contents)) {
+    var parsed;
+
     try {
-      parsed = matter(file.contents.toString());
+      parsed = matter(file.contents.toString(), options);
     } catch (e) {
-      var errMsg = 'Invalid frontmatter in file'
+      var errMsg = 'Invalid frontmatter in file';
       if (filePath !== undefined) errMsg += ": " + filePath;
@@ -50,11 +53,10 @@ var err = new Error(errMsg);
  *
+ * @param {Object} options - Options to pass on to `gray-matter`
  * @return {Function}
  */
 
-function frontmatter(){
-  return function(files){
-    for (path in files) {
-      extractFrontmatter(files[path], path)
-    }
-  };
+function frontmatter(options){
+  return each(function(file, filePath){
+    extractFrontmatter(file, filePath, options);
+  });
 }

package.json

 {
   "name": "metalsmith-matters",
-  "version": "1.0.0",
-  "description": "A Metalsmith plugin to read metadata from YAML frontmatter",
+  "version": "1.1.0",
+  "description": "A Metalsmith plugin to read file metadata from frontmatter",
   "main": "lib/index.js",
@@ -24,3 +24,4 @@ "scripts": {
     "gray-matter": "^2.0.1",
-    "is-utf8": "^0.2.0"
+    "is-utf8": "^0.2.0",
+    "metalsmith-each": "^0.1.1"
   },
@@ -27,0 +28,0 @@ "devDependencies": {

README.md

@@ -1,14 +0,43 @@
-# metalsmith-matters
+# metalsmith-matters [![Build Status](https://travis-ci.org/Ajedi32/metalsmith-matters.svg)](https://travis-ci.org/Ajedi32/metalsmith-matters)
 
-A Metalsmith plugin to read metadata from YAML frontmatter
+A [Metalsmith](https://github.com/segmentio/metalsmith) plugin to read file
+metadata from frontmatter. Supports all frontmatter formats supported by the
+[gray-matter](https://github.com/jonschlinkert/gray-matter#optionslang)
+library (including YAML, JSON, TOML, CSON, and more).
 
-"But wait!" you say, "doesn't Metalsmith already have that built-in"? Well, yes. For now anyway. This plugin is an attempt to extract that functionality out of the core
+"But wait!" you say. "Doesn't Metalsmith already have frontmatter parsing
+built-in"? Well, yes. For now anyway. This plugin is an attempt to extract that
+functionality out of the Metalsmith core. Eventually the goal is to have
+frontmatter parsing removed from the Metalsmith core entirely in favor of this
+plugin or a similar one (see
+[segmentio/metalsmith#157](https://github.com/segmentio/metalsmith/issues/157)).
 
+Even in the absence of that change though, this plugin has two key advantages
+over the built-in frontmatter parsing in Metalsmith. Firstly, it's composable
+with other plugins. For example, you could use it with
+[`metalsmith-branch`](https://github.com/ericgj/metalsmith-branch) to turn on
+frontmatter parsing for only a subset of files, or you could place it *after*
+[`metalsmith-s3`](https://github.com/mwishek/metalsmith-s3) in the plugin list
+so that it parses frontmatter in downloaded files. Secondly, this plugin
+provides a way to pass options to the underlying frontmatter parsing library,
+[gray-matter](https://github.com/jonschlinkert/gray-matter). This allows you to
+do things like
+[change the delimiter used to separate frontmatter from the rest of the file](https://github.com/jonschlinkert/gray-matter#optionsdelims),
+or
+[set TOML as the default frontmatter format](https://github.com/jonschlinkert/gray-matter#optionslang).
+These are all things you can't do with Metalsmith's built-in frontmatter
+parsing.
+
+
 ## Installation
 
-  npm install --save metalsmith-matters
+    npm install --save metalsmith-matters
 
 ## CLI Usage
 
-After installing metalsmith-matters, simply add the `metalsmith-matters` key to the plugins in your `metalsmith.json` file. Be sure to include it *before* any plugins which need to use the metadata in your frontmatter, or which expect as input files with no frontmatter header. Generally speaking, this means that metalsmith-matters should be the first plugin in the list.
+After installing metalsmith-matters, simply add the `metalsmith-matters` key to
+the plugins in your `metalsmith.json` file. Be sure to include it *before* any
+plugins which need to use the metadata in your frontmatter, or which expect as
+input files with no frontmatter header. Generally speaking, this means that
+metalsmith-matters should be the first plugin in the list.
 
@@ -18,3 +47,5 @@ ```javascript
   "plugins": {
-    "metalsmith-matters": true
+    "metalsmith-matters": {
+      // Options
+    }
     // Other plugins...
@@ -27,3 +58,9 @@ }
 
-After installing metalsmith-matters, you can require `metalsmith-matters` in your code, then call the exported value to initialize the plugin and pass the result to `Metalsmith.use` (just as you would with any other Metalsmith plugin). Again, be sure to use metalsmith-matters *before* any plugins which need to use the metadata defined your frontmatter, or which expect as input files with no frontmatter header. Generally speaking, this means that metalsmith-matters should be the first plugin in the list.
+After installing metalsmith-matters, you can require `metalsmith-matters` in
+your code, then call the exported value to initialize the plugin and pass the
+result to `Metalsmith.use` (just as you would with any other Metalsmith plugin).
+Again, be sure to use metalsmith-matters *before* any plugins which need to use
+the metadata defined your frontmatter, or which expect as input files with no
+frontmatter header. Generally speaking, this means that metalsmith-matters
+should be the first plugin in the list.
 
@@ -34,3 +71,6 @@ ```javascript
 Metalsmith(__dirname)
-  .use(frontmatter())
+  .frontmatter(false) // Disable built-in frontmatter parsing (recommended)
+  .use(frontmatter({
+    // Options
+  }))
   .use(/* Other plugins... */)
@@ -41,1 +81,16 @@ .build(function(err) {
 ```
+
+# Options
+
+metalsmith-matters supports all the options supported by
+[`gray-matter`](https://github.com/jonschlinkert/gray-matter),
+metalsmith-matters' underlying frontmatter parsing library (it's the same one
+used by the Metalsmith core). These include:
+
+* `parser`
+* `eval`
+* `lang`
+* `delims`
+
+For details on how to use these options, see the
+[documentation for `gray-matter`](https://github.com/jonschlinkert/gray-matter#options).

test/index.js

@@ -6,3 +6,3 @@ var assert = require('assert');
 describe('metalsmith-matters', function(){
-  it('should add add metadata based on the frontmatter in the file', function(done){
+  it('should add metadata based on the frontmatter in the file', function(done){
     Metalsmith('test/fixtures/basic')
@@ -20,2 +20,3 @@ .frontmatter(false)
     Metalsmith('test/fixtures/basic')
+      .frontmatter(false)
       .use(frontmatter())
@@ -28,2 +29,23 @@ .build(function(err, files){
   });
+
+  describe('options', function(){
+    // Given that all metalsmith-matters options are currently implemented by
+    // simply passing the options argument to gray-matter, I believe testing
+    // only one of gray-matter's options is sufficient coverage of this feature.
+    // If the implementation changes in the future, more comprehensive test
+    // coverage may be necessary.
+
+    describe('delims', function(){
+      it('should set the delimiters used for frontmatter', function(done) {
+        Metalsmith('test/fixtures/delimiters-option')
+          .frontmatter(false)
+          .use(frontmatter({delims: ['~~~', '~~~']}))
+          .build(function(err, files){
+            if (err) return done(err);
+            assert.equal(files["test.md"].someKey, "value");
+            done();
+          });
+      });
+    });
+  });
 });

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

9774

increased by55.46%

Number of package files

10

increased by25%

Lines of code

95

increased by28.38%

Number of lines in readme file

93

increased by144.74%

Worsened metrics

Dependency count

3

increased by50%

Dependency changes

• + Addedmetalsmith-each@^0.1.1

• + Addedmetalsmith-each@0.1.1(transitive)