sounisi5011/metalsmith-directory-metadata

# {{{pkg.name}}}

[![npm package](https://img.shields.io/npm/v/{{{pkg.name}}}.svg)][npm]
[![License: {{{pkg.license}}}](https://img.shields.io/static/v1?label=license&message={{#encURL}} {{{pkg.license}}} {{/encURL}}&color=green)][github-license]
![Supported Node version: {{{pkg.engines.node}}}](https://img.shields.io/static/v1?label=node&message={{#encURL}} {{{pkg.engines.node}}} {{/encURL}}&color=brightgreen)
![Type Definitions: TypeScript](https://img.shields.io/npm/types/{{{pkg.name}}}.svg)
[![bundle size](https://badgen.net/bundlephobia/min/{{{pkg.name}}}@{{{pkg.version}}})](https://bundlephobia.com/result?p={{{pkg.name}}}@{{{pkg.version}}})
[![Dependencies Status](https://david-dm.org/sounisi5011/{{{pkg.name}}}/status.svg)](https://david-dm.org/sounisi5011/{{{pkg.name}}})
[![Build Status](https://travis-ci.com/sounisi5011/{{{pkg.name}}}.svg?branch=master)](https://travis-ci.com/sounisi5011/{{{pkg.name}}})
[![Maintainability Status](https://api.codeclimate.com/v1/badges/4dcb19ba4651279775d5/maintainability)](https://codeclimate.com/github/sounisi5011/{{{pkg.name}}}/maintainability)

[npm]: https://www.npmjs.com/package/{{{pkg.name}}}
[github-license]: https://github.com/sounisi5011/{{{pkg.name}}}/blob/v{{{pkg.version}}}/LICENSE

Defines default metadata for files in a directory.

## Features

*   can define directory metadata

    This plugin defines the metadata that all files in the directory have in common.  
    Directory metadata is defined using a definition file in JSON or YAML format.

## Install

```sh
npm install {{{pkg.name}}}
```

## CLI Usage

Install via npm and then add the `{{{pkg.name}}}` key to your `metalsmith.json` plugin, like so:

```json
{
  "plugins": {
    "{{{pkg.name}}}": true
  }
}
```

If you need to specify an options, set the options to the value of the `{{{pkg.name}}}` key.

```json
{
  "plugins": {
    "{{{pkg.name}}}": {
      "pattern": "**/.metadata"
    }
  }
}
```

See [Metalsmith CLI] for more details.

[Metalsmith CLI]: https://github.com/segmentio/metalsmith#cli

## Javascript Usage

The simplest use is to omit the option. By [default](#options), the following files are used to define metadata: `metadata.yaml`, `metadata.yml`, `metadata.json`, and `metadata`.

```js
const directoryMetadata = require('{{{pkg.name}}}');

metalsmith
  .use(directoryMetadata());
```

If you need to specify an options, set the options value.

```js
const directoryMetadata = require('{{{pkg.name}}}');

metalsmith
  .use(directoryMetadata({
    pattern: '**/.metadata',
  }));
```

If you want to use the `files` variable or the default options value, you can specify the callback function that generates the options.

```js
const directoryMetadata = require('{{{pkg.name}}}');

metalsmith
  .use(directoryMetadata(
    (files, metalsmith, defaultOptions) => {
      return {
        pattern: [...defaultOptions.pattern, '**/.metadata'],
      };
    }
  ));
```

## TypeScript Usage

For compatibility with the [Metalsmith CLI], this package exports single function in CommonJS style.  
When using with TypeScript, it is better to use the [`import = require()` statement](https://www.typescriptlang.org/docs/handbook/modules.html#export--and-import--require).

```js
import directoryMetadata = require('{{{pkg.name}}}');

metalsmith
  .use(directoryMetadata());
```

## Options

The default value for options are [defined](https://github.com/sounisi5011/{{{pkg.name}}}/blob/v{{{pkg.version}}}/src/options.ts#L16-L18) like this:

```js
{
  pattern: ['**/metadata.{json,yaml,yml}', '**/metadata'],
}
```

### `pattern`

Specifies the Glob pattern that matches the file that defines the directory metadata.  
Specify a glob expression string or an array of strings as the pattern.  
Pattern are verified using [multimatch v{{{pkgLock.dependencies.multimatch.version}}}][npm-multimatch-used].

[npm-multimatch-used]: https://www.npmjs.com/package/multimatch/v/{{{pkgLock.dependencies.multimatch.version}}}

Default value ([source](https://github.com/sounisi5011/{{{pkg.name}}}/blob/v{{{pkg.version}}}/src/options.ts#L17)):

```js
['**/metadata.{json,yaml,yml}', '**/metadata']
```

Type definition ([source](https://github.com/sounisi5011/{{{pkg.name}}}/blob/v{{{pkg.version}}}/src/options.ts#L5)):

```ts
string | string[]
```

## Debug mode

This plugin supports debugging output.  
To enable, use the following command when running your build script:

```sh
DEBUG={{{pkg.name}}},{{{pkg.name}}}:* node my-website-build.js
```

For more details, please check the description of [debug v{{{pkgLock.dependencies.debug.version}}}][npm-debug-used].

[npm-debug-used]: https://www.npmjs.com/package/debug/v/{{{pkgLock.dependencies.debug.version}}}

## Tests

To run the test suite, first install the dependencies, then run `npm test`:

```sh
npm install
npm test
```

## Contributing

see [CONTRIBUTING.md](https://github.com/sounisi5011/{{{pkg.name}}}/blob/master/CONTRIBUTING.md)