README.md (6878B)
1 # section-matter [](https://www.npmjs.com/package/section-matter) [](https://npmjs.org/package/section-matter) [](https://npmjs.org/package/section-matter) [](https://travis-ci.org/jonschlinkert/section-matter) 2 3 > Like front-matter, but supports multiple sections in a document. 4 5 Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support. 6 7 ## Install 8 Install with [npm](https://www.npmjs.com/): 9 10 ```sh 11 $ npm install --save section-matter 12 ``` 13 14 ## Usage 15 16 **Params** 17 18 * `input` **{String|Buffer|Object}**: If input is an object, it's `content` property must be a string or buffer. 19 * **{Object}**: options 20 * `returns` **{Object}**: Returns an object with a `content` string and an array of `sections` objects. 21 22 **Example** 23 24 ```js 25 var sections = require('{%= name %}'); 26 var result = sections(input, options); 27 // { content: 'Content before sections', sections: [] } 28 ``` 29 30 See available [options](#options). 31 32 ## Example 33 34 _With the exception of front-matter, **which must be the very first thing in the string**, the opening delimiter of all other sections must be followed by a string to be used as the `key` for the section._ 35 36 Given the following string: 37 38 ``` 39 Content before the sections. 40 41 --- 42 43 More content. 44 45 ---one 46 title: One 47 --- 48 49 This is the first section. 50 ``` 51 52 The following code: 53 54 ```js 55 console.log(sections(input)); 56 ``` 57 58 Results in: 59 60 ```js 61 { 62 content: 'Content before the sections.\n\n---\n\nMore content.\n', 63 sections: [ 64 { 65 key: 'one', 66 data: 'title: One', 67 content: '\nThis is the first section.' 68 } 69 ] 70 } 71 ``` 72 73 ## Options 74 75 ### options.section_parse 76 77 **Type**: `function` 78 79 **Default**: `undefined` 80 81 Function to be called on each section after it's parsed from the string. 82 83 **Example** 84 85 Given the following string (`foo.md`): 86 87 ``` 88 This is content before the sections. 89 90 ---one 91 title: First section 92 --- 93 94 This is section one. 95 96 ---two 97 title: Second section 98 --- 99 100 This is section two. 101 ``` 102 103 Using the following custom `section_parse` function: 104 105 ```js 106 var fs = require('fs'); 107 var path = require('path'); 108 var yaml = require('js-yaml'); 109 var sections = require('section-matter'); 110 111 var str = fs.readFileSync('foo.md'); 112 var options = { 113 section_parse: function(section) { 114 console.log(section) 115 section.key = 'section-' + section.key; 116 section.data = yaml.safeLoad(section.data); 117 } 118 }; 119 120 var result = sections(str, options); 121 console.log(result); 122 ``` 123 124 Results in: 125 126 ```js 127 { 128 content: 'This is content before the sections.\n', 129 sections: [ 130 { 131 key: 'section-one', 132 data: { title: 'First section' }, 133 content: '\nThis is section one.\n' 134 }, 135 { 136 key: 'section-two', 137 data: { title: 'Second section' }, 138 content: '\nThis is section two.\n' 139 } 140 ] 141 } 142 ``` 143 144 ### options.section_delimiter 145 146 **Type**: `string` 147 148 **Default**: `---` 149 150 Delimiter to use as the separator for sections. _With the exception of front-matter, which must be the very first thing in the string, the opening delimiter of all other sections must be followed by a string to be used as the `key` for the section._ 151 152 **Example** 153 154 ```js 155 var input = '~~~\ntitle: bar\n~~~\n\nfoo\n~~~one\ntitle: One\n~~~\nThis is one'; 156 console.log(sections(input, {section_delimiter: '~~~'})); 157 ``` 158 159 Results in: 160 161 ```js 162 { 163 content: '', 164 sections: [ 165 { 166 key: '', 167 data: 'title: bar', 168 content: '\nfoo' 169 }, 170 { 171 key: 'one', 172 data: 'title: One', 173 content: 'This is one' 174 } 175 ] 176 } 177 ``` 178 179 ## About 180 <details> 181 <summary><strong>Contributing</strong></summary> 182 183 Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new). 184 185 Please read the [contributing guide](.github/contributing.md) for advice on opening issues, pull requests, and coding standards. 186 187 </details> 188 189 <details> 190 <summary><strong>Running Tests</strong></summary> 191 192 Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command: 193 194 ```sh 195 $ npm install && npm test 196 ``` 197 198 </details> 199 200 <details> 201 <summary><strong>Building docs</strong></summary> 202 203 _(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_ 204 205 To generate the readme, run the following command: 206 207 ```sh 208 $ npm install -g verbose/verb#dev verb-generate-readme && verb 209 ``` 210 211 </details> 212 213 ### Related projects 214 215 You might also be interested in these projects: 216 217 - [assemble](https://www.npmjs.com/package/assemble): Get the rocks out of your socks! Assemble makes you fast at creating web projects… [more](https://github.com/assemble/assemble) | [homepage](https://github.com/assemble/assemble "Get the rocks out of your socks! Assemble makes you fast at creating web projects. Assemble is used by thousands of projects for rapid prototyping, creating themes, scaffolds, boilerplates, e-books, UI components, API documentation, blogs, building websit") 218 - [gray-matter](https://www.npmjs.com/package/gray-matter): Parse front-matter from a string or file. Fast, reliable and easy to use. Parses YAML… [more](https://github.com/jonschlinkert/gray-matter) | [homepage](https://github.com/jonschlinkert/gray-matter "Parse front-matter from a string or file. Fast, reliable and easy to use. Parses YAML front matter by default, but also has support for YAML, JSON, TOML or Coffee Front-Matter, with options to set custom delimiters. Used by metalsmith, assemble, verb and ") 219 - [verb](https://www.npmjs.com/package/verb): Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… [more](https://github.com/verbose/verb) | [homepage](https://github.com/verbose/verb "Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used on hundreds of projects of all sizes to generate everything from API docs to readmes.") 220 221 ### Contributors 222 223 ### Author 224 **Jon Schlinkert** 225 226 + [github/jonschlinkert](https://github.com/jonschlinkert) 227 + [twitter/jonschlinkert](https://twitter.com/jonschlinkert) 228 229 ### License 230 Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert). 231 Released under the [MIT License](LICENSE). 232 233 *** 234 235 _This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on October 23, 2017._ 236