https://github.com/metalsmith/metadata
A metalsmith plugin to load global metadata from files.
https://github.com/metalsmith/metadata
metadata metalsmith metalsmith-plugin
Last synced: 6 months ago
JSON representation
A metalsmith plugin to load global metadata from files.
- Host: GitHub
- URL: https://github.com/metalsmith/metadata
- Owner: metalsmith
- License: mit
- Created: 2014-03-06T19:09:17.000Z (over 11 years ago)
- Default Branch: main
- Last Pushed: 2023-07-23T17:50:43.000Z (about 2 years ago)
- Last Synced: 2024-10-30T00:10:25.474Z (12 months ago)
- Topics: metadata, metalsmith, metalsmith-plugin
- Language: JavaScript
- Homepage:
- Size: 1.27 MB
- Stars: 41
- Watchers: 40
- Forks: 19
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# @metalsmith/metadata
A metalsmith plugin to load global metadata from files and directories.
[![metalsmith: plugin][metalsmith-badge]][metalsmith-url]
[![npm: version][npm-badge]][npm-url]
[![travis: build][ci-badge]][ci-url]
[![code coverage][codecov-badge]][codecov-url]
[![license: MIT][license-badge]][license-url]
- Reads, parses and merges data files into global metadata and removes them from the build (when applicable).
- Supports JSON, YAML and TOML files. [TOML parser](https://www.npmjs.com/package/toml) needs to be installed separately.
- Supports dot-notated metadata keypath targets as option keys, eg `{'config.nav': 'src/config/nav.yml'}`
## Installation
NPM:
```bash
npm install @metalsmith/metadata
```
Yarn:
```bash
yarn add @metalsmith/metadata
```
## Usage
Pass the options to `Metalsmith#use`. The options object is in the format `{ 'metadata.key': 'path/to/(file.ext|dir)' }`. Relative file/directory paths are resolved to `metalsmith.directory()`. Directory option keys will include direct children of the directory, see [Mapping nested metadata directories](#mapping-nested-metadata-directories) for creating nested directory structures.
```js
import Metalsmith from 'metalsmith'
import metadata from '@metalsmith/metadata'
const __dirname = dirname(new URL(import.meta.url).pathname)
Metalsmith(__dirname)
.use(
metadata({
// in-source JSON file
jsonFile: 'src/data/a-json-file.json',
// out-of-source YAML file at nested keypath
'nested.yamlFile': 'some-directory/a-yaml-file.yaml',
// out-of-source directory
aDirectory: 'some-directory/a-directory'
})
)
.build((err) => {
console.log(metalsmith.metadata())
// logs { jsonFile: {...}, nested: { yamlFile: {...}}, aDirectory: {...} }
})
```
Files inside `metalsmith.source()` will be considered metadata and thus removed from the build output.
### Plugin order
Typically, you want to use this plugin somewhere at the start of the chain, before any rendering plugins run, like [@metalsmith/layouts](https://github.com/metalsmith/layouts) or [@metalsmith/in-place](https://github.com/metalsmith/in-place).
### Merging metadata files into objects
You can merge metadata files into objects by making the root of the data file an object. For example, given the following 2 files:
src/themes/red.jsonsrc/themes/blue.json
{
"red": {
"primary-color": "#FF0000"
}
}
{
"blue": {
"primary-color": "#00FF00"
}
}
with a usage like `metalsmith.use(metadata({ themes: 'src/themes' }))`, `metalsmith.metadata().themes` will be `{ red: {"primary-color": #00FF00"}, blue: {"primary-color": "#00FF00"}}`.
### Merging metadata files into arrays
You can merge metadata files into an array by making the root of the data file an array. For example, given the following 2 files:
src/themes/red.jsonsrc/themes/blue.json
[
{
"primary-color": "#FF0000"
}
]
[
{
"primary-color": "#00FF00"
}
]
with a usage like `metalsmith.use(metadata({ themes: 'src/themes' }))`, `metalsmith.metadata().themes` will be `[{"primary-color": #00FF00"}, {"primary-color": "#00FF00"}]`.
### Mapping nested metadata directories
You can map nested metadata directories by specifying multiple options:
```js
metalsmith.use(
metadata({
config: 'src/config',
'config.theme': 'src/config/theme',
'config.theme.summer': 'src/config/theme/summer',
'config.constants': 'src/config/constants.yaml'
})
)
```
The resulting metadata will have a structure like:
```js
{
...otherMetadata,
config: {
...metadata_from_config_dir
theme: {
...metadata_from_config_theme_dir
summer: { ...metadata_from_config_theme_summer_dir }
}
},
constants: {
...metadata_from_config_constants_file
}
}
```
## Debug
To enable debug logs, set the `DEBUG` environment variable to `@metalsmith/metadata`:
```js
metalsmith.env('DEBUG', '@metalsmith/metadata*')
```
## CLI Usage
To use this plugin with the Metalsmith CLI,add the `@metalsmith/metadata` key to your `metalsmith.json` plugins. Each key in the dictionary of options will be the key for the global metadata object, like so:
```json
{
"plugins": {
"@metalsmith/metadata": {
"authors": "src/authors.json",
"categories": "src/categories.yaml",
"customers": "external_data/customers"
}
}
}
```
## License
[MIT][license-url]
[npm-badge]: https://img.shields.io/npm/v/@metalsmith/metadata.svg
[npm-url]: https://www.npmjs.com/package/@metalsmith/metadata
[ci-badge]: https://github.com/metalsmith/metalsmith/actions/workflows/test.yml/badge.svg
[ci-url]: https://github.com/metalsmith/metalsmith/actions/workflows/test.yml
[metalsmith-badge]: https://img.shields.io/badge/metalsmith-core_plugin-green.svg?longCache=true
[metalsmith-url]: https://metalsmith.io
[codecov-badge]: https://img.shields.io/coveralls/github/metalsmith/metadata
[codecov-url]: https://coveralls.io/github/metalsmith/metadata
[license-badge]: https://img.shields.io/github/license/metalsmith/metadata
[license-url]: LICENSE