awoo-matter

    1.1.1 • Public • Published

    awoo-matter

    A front matter parsing plugin for the awoo static site generator

    npm version code style: standard

    Features

    • Extract YAML metadata (Front Matter) from text files within the awoo files array
    • Custom filter functions to include or exclude files from transforms

    Installation

    npm install --save awoo-matter

    Usage example

    const awoo = require('awoo')
    const matter = require('awoo-matter')
     
    // enter our main function:
    // the main function should be an async function so that
    // it automatically returns a promise
    awoo(async site => {
      // we register our plugin...
      site.use(matter)
      // ...and initiate the build process
      return site
    })

    Filter example

    You can pass a custom filter as an option to matter to include or exclude files.

    A filter is a function that takes the arguments file, options, and files. file is the current file, options is the options object passed to matter, and files is the entire array of files created by awoo.

    When the filter function returns true, matter applies its transforms to the current file object. Otherwise the file object remains unchanged.

    The default filter in matter always returns true, so the transform will be applied to every file:

    function filter (file, options, files) {
      return true
    }

    This is how you could use a filter to only apply matter to files ending with .md:

    const awoo = require('awoo')
    const matter = require('awoo-matter')
     
    // custom filter function
    // returns true if file path ends with '.md'
    function myCustomFilter (file, options, files) {
      return file.path.endsWith('.md')
    }
     
    awoo(async site => {
      // we register the matter plugin with our custom filter function...
      site.use(matter, {filter: myCustomFilter})
      // ...and initiate the build process
      return site
    })

    Options Example

    matter uses [gray-matter](http://npm.im/gray-matter) for parsing metadata. All options of gray-matter are also available in matter.

    This is what a plugin call with custom options would look like:

    const awoo = require('awoo')
    const matter = require('awoo-matter')
     
    // we define our options object...
    const myMatterOptions = {
      delims: '~~~'
    }
     
    awoo(async site => {
      // ...and pass it to the use method
      site.use(matter, myMatterOptions)
      return site
    })

    How does it work?

    matter extracts any Front Matter from the contents property of a file object and writes it to its metadata property.

    Given the following text file:

    ---
    title: Greeting
    ---
    Hello World
    

    The resulting awoo file object would be:

    contents: 'Hello World',
    metadata: {
      title: 'Greeting'
    }

    Maintainers

    Code of Conduct

    This repository operates under the weallbehave Code of Conduct. Its contents can be found in CODE_OF_CONDUCT.md.

    License

    MIT (see LICENSE document)

    Install

    npm i awoo-matter

    DownloadsWeekly Downloads

    2

    Version

    1.1.1

    License

    MIT

    Last publish

    Collaborators

    • oceanseraph