From 58a62972d5cbcf6a2c46203173dee3e71693e1e4 Mon Sep 17 00:00:00 2001
From: Ben Wilcox <reccanti@gmail.com>
Date: Wed, 8 Nov 2017 23:44:58 -0500
Subject: [PATCH] Update excerpt documentation and examples

Shows how to pass a function to the excerpt option parameter in the
.verb README and in the examples folder.
---
 .verb.md            | 52 +++++++++++++++++++++++++++++++++++++++------
 examples/excerpt.js | 28 +++++++++++++++++++++---
 2 files changed, 71 insertions(+), 9 deletions(-)

diff --git a/.verb.md b/.verb.md
index 9a39e80..e72511d 100644
--- a/.verb.md
+++ b/.verb.md
@@ -168,26 +168,66 @@ $ node examples/<example_name>
 
 ### options.excerpt
 
-**Type**: `Object`
+**Type**: `Boolean|Function`
 
 **Default**: `undefined`
 
 Extract an excerpt that directly follows front-matter, or is the first thing in the string if no front-matter exists.
 
+If set to `excerpt: true`, it will look for the frontmatter delimiter, `---` by default and grab everything leading up to it.
+
+**Example**
+
+```js
+var file = matter([
+  '---',
+  'foo: bar',
+  '---',
+  'This is an excerpt.',
+  '---',
+  'This is content'
+].join('\n'), {excerpt: true});
+```
+
+Results in:
+
+```js
+{ 
+	content: 'This is an excerpt.\n---\nThis is content',
+	data: { foo: 'bar' },
+	excerpt: 'This is an excerpt.\n' 
+}
+```
+
+You can also set `excerpt` to a function. This function uses the 'file' and 'options' that were initially passed to gray-matter as parameters, so you can control how the excerpt is extracted from the content.
+
 **Example**
 
 ```js
-var str = '--\ntitle: Home\n---\nAn excerpt\n---\nOther stuff';
-console.log(matter(str, {excerpt: true}));
+// returns the first 4 lines of the contents
+function firstFourLines(file, options) {
+    file.excerpt = file.content.split('\n').slice(0, 4).join(' ');
+}
+
+var file =  matter([
+  '---',
+  'foo: bar',
+  '---',
+  'Only this',
+  'will be',
+  'in the',
+  'excerpt',
+  'but not this...'
+].join('\n'), {excerpt: firstFourLines});
 ```
 
 Results in:
 
 ```js
 { 
-  data: { title: 'Home'}, 
-  excerpt: '\nAn excerpt', 
-  content: '\nAn excerpt\n---\nOther stuff' 
+	content: 'Only this\nwill be\nin the\nexcerpt\nbut not this...',
+	data: { foo: 'bar' },
+	excerpt: 'Only this will be in the excerpt'
 }
 ```
 
diff --git a/examples/excerpt.js b/examples/excerpt.js
index 8918a52..f263585 100644
--- a/examples/excerpt.js
+++ b/examples/excerpt.js
@@ -3,7 +3,8 @@ var matter = require('..');
 var fixture = path.join.bind(path, __dirname, 'fixtures');
 var magenta = require('ansi-magenta');
 
-var file = matter([
+// excerpt as a boolean
+var file1 = matter([
   '---',
   'foo: bar',
   '---',
@@ -12,5 +13,26 @@ var file = matter([
   'This is content'
 ].join('\n'), {excerpt: true});
 
-console.log(magenta('/* excerpt */'));
-console.log(file);
+console.log(magenta('/* excerpt: true */'));
+console.log(file1);
+
+// excerpt as a function
+
+// returns the first 4 lines of the contents
+function firstFourLines(file, options) {
+  file.excerpt = file.content.split('\n').slice(0, 4).join(' ');
+}
+
+var file2 =  matter([
+'---',
+'foo: bar',
+'---',
+'Only this',
+'will be',
+'in the',
+'excerpt',
+'but not this...'
+].join('\n'), {excerpt: firstFourLines });
+
+console.log(magenta('/* excerpt: function(file, options) { ... } */'));
+console.log(file2);
\ No newline at end of file